densemaps.numpy.maps¶

Classes

`EmbKernelDenseDistMap`(emb1, emb2[, blur, ...])	Kernel Map, computed from embeddings.
`EmbP2PMap`(emb1, emb2[, n_jobs])	Point to point map, computed from embeddings.
`EmbPreciseMap`(emb1, emb2, faces1[, n_jobs])	Point to barycentric map, computed from embeddings.
`KernelDenseDistMap`(log_matrix[, lse_row, ...])	Map represented by a row-normalized dense matrix obtained from an element-wise exponential.
`P2PMap`(p2p_21[, n1])	Point to point map from a set S2 to a set S1.
`PointWiseMap`([array_names])	Root class representing a pointwise map.
`PreciseMap`(v2face_21, bary_coords, faces1[, n1])	Point to barycentric map from a set S2 to a surface S1.
`SparseMap`(map)	Map represented by a sparse matrix.

class densemaps.numpy.maps.PointWiseMap(array_names=None)¶

Root class representing a pointwise map. Not supposed to be instanciated in itself.

A pointwise, denoted \(P : S_2 \to S_1\), is a map that associates to each point x in \(S_2\) a point \(P(x)\) in \(S_1\). It can usually be represented as a \(n_2 \times n_1\) matrix, where \(n_2\) is the number of points in \(S_2\) and \(n_1\) the number of points in \(S_1\).

Given a pointwise map \(P\), the pullback of a function \(f : S_1 \to R\) is a function \(f_{pb} : S_2 \to R\) defined by \(f_{pb}(x) = f(P(x))\). In practice it can easily be computed by matrix multiplication: \(f_{pb} = P f\).

However, we usually don’t need to use the exact values inside \(P\), but rather only care about multiplying with some functions, extracting maximal values per-row or per-column, or summing on rows or columns.

array_names¶

Names of the arrays stored in the object. Used to transfer to torch and to GPU.

Type:: list of str

is_index_map¶

Whether the map is intrinsically stored as a one-nonzero-per-row index array (i.e. a vertex-to-vertex map). False for all matrix-valued representations.

Type:: bool

pull_back(f)¶

Pull back a function \(f\). Three possibilities:

f is a function on S1, of shape (N1,), then the output is a function on S2, of shape (N2,)
f represents multiple function on S1, of shape (N1, p), then the output is a function on S2, of shape (N2, p)
f represents a batch multiple function on S1, of shape (B, N1, p), then the output is a function on S2, of shape (B, N2, p)

Note that the case where f is a batch of a single function (B, N1) is not supported, and one should then use f[…, None]

Parameters:: f (np.ndarray) – (N1,), (N1, p) or (B, N1, p)
Returns:: f_pb – (N2,), (N2, p) or (B, N2, p)
Return type:: np.ndarray

property shape¶

Shape of the map.

Returns:: shape – Depends on the representation
Return type:: tuple

property ndim¶

Number of dimensions of the map.

Returns:: ndim – Number of dimensions
Return type:: int

get_nn()¶

Outputs the nearest neighbor map. The nearest neighbor map is the map that associates to each point of S2 the index of the closest point in S1.

Returns:: nn_map – (N2,) or (B, N2) depending on the representation
Return type:: np.ndarray

property mT¶

Returns the transpose of the map.

Returns the transpose of the matrix representation of the map.

Returns:: map_t – Transpose map
Return type:: PointWiseMap

class densemaps.numpy.maps.SparseMap(map)¶

Map represented by a sparse matrix.

The sparse matrix is of size (N2, N1).

Parameters:: map (scipy.sparse.csr_matrix) – (N2, N1) or (N2, N1)

property shape¶

Shape of the map.

Returns:: shape – (N2, N1)
Return type:: tuple

property mT¶

Returns the transpose of the map.

Returns the transpose of the matrix representation of the map.

Returns:: map_t – Transpose map
Return type:: PointWiseMap

pull_back(f)¶

Pull back a function \(f\). Two possibilities:

# f is a function on S1, of shape (N1,), then the output is a function on S2, of shape (N2,) # f represents multiple function on S1, of shape (N1, p), then the output is a function on S2, of shape (N2, p)

Parameters:: f (np.ndarray) – (N1,), (N1, p)
Returns:: f_pb – (N2,), (N2, p)
Return type:: np.ndarray

get_nn()¶

Outputs the nearest neighbor map. The nearest neighbor map is the map that associates to each point of S2 the index of the closest point in S1. Simple argmax along the last dimension.

Returns:: nn_map – (N2,) on the representation
Return type:: np.ndarray

to_dense()¶: Returns the dense (N2, N1) matrix representation of the map.

class densemaps.numpy.maps.P2PMap(p2p_21, n1=None)¶

Point to point map from a set S2 to a set S1. Defined by a map \(P_{21} : S2 \to S1\) or an array p2p_21 of size (n_2), where p2p_21[i] is the index of the point in S1 closest to the point i in S2. Batched versions are accepted

Parameters:

p2p_21 ((n2,) or (B, n2))
n1 (int or None) – Number of points in S1. If None, n1 = p2p.max()+1

property shape¶

Shape of the map, as a matrix.

Even though the map is stored as an index array (see is_index_map), its shape is reported as a matrix for consistency with the other representations. The underlying index array is available as self.p2p_21 (shape (N2,)/(B, N2)).

Returns:: shape – (N2, N1), or (B, N2, N1) for a batched map
Return type:: tuple

property n1¶

Number of vertices on the first shape. Estimated if not provided as input.

Returns:: n1
Return type:: int

pull_back(f)¶

Pull back a function \(f\). Four possibilities:

f is a function on S1, of shape (N1,), then the output is a function on S2, of shape (N2,) (or (B, N2,) if the map is batched)
f represents multiple function on S1, of shape (N1, p), then the output is a function on S2, of shape (N2, p) (or (B, N2, p) if the map is batched)
f represents a batch multiple function on S1, of shape (B, N1, p), then the output is a function on S2, of shape (B, N2, p)

Note tht the case where f is a batch of a single function (B, N1) is not supported, and one should then use f[…, None]

Parameters:: f (np.ndarray) – (N1,), (N1, p) or (B, N1, p)
Returns:: f_pb – (N2,), (N2, p) or (B, N2, p)
Return type:: np.ndarray

get_nn()¶

Outputs the nearest neighbor map. The nearest neighbor map is the same as the input.

Returns:: nn_map – (N2,) or (B, N2) depending on the representation
Return type:: np.ndarray

property mT¶

Returns the transpose of the map.

Returns the transpose of the matrix representation of the map.

Returns:: map_t – Transpose map
Return type:: PointWiseMap

to_dense()¶: Returns the dense (N2, N1) matrix representation of the map.

class densemaps.numpy.maps.PreciseMap(v2face_21, bary_coords, faces1, n1=None)¶

Point to barycentric map from a set S2 to a surface S1. Batched Version is not supported yet.

Is represented as a sparse matrix of size (N2, N1), where there are at most 3 non-zero entries per row, which sum to 1.

Parameters:

v2face_21 (np.ndarray) – (n2,) Indices of the faces of S1 closest to each point of S2.
bary_coords (np.ndarray) – (n2, 3) Barycentric coordinates of the points of S2 in the faces of S1.
faces1 (np.ndarray) – (N1, 3) All the Faces of S1.
n1 (int, optional) – Number of vertices of S1. If None, inferred as faces1.max()+1, which is only correct if every vertex of S1 belongs to at least one face.

class densemaps.numpy.maps.EmbP2PMap(emb1, emb2, n_jobs=1)¶

Point to point map, computed from embeddings.

Simple wrapper around P2PMap

Parameters:

emb1 (np.ndarray) – (N1, p) or (B, N1, p)
emb2 (np.ndarray) – (N2, p) or (B, N2, p)
n_jobs (int) – Number of jobs to use for the NN query

class densemaps.numpy.maps.EmbPreciseMap(emb1, emb2, faces1, n_jobs=1)¶

Point to barycentric map, computed from embeddings.

Simple wrapper around PreciseMap

Parameters:

emb1 (np.ndarray) – (N1, K)
emb2 (np.ndarray) – (N2, K)
faces1 (np.ndarray) – (N1, 3)
n_jobs (int) – Number of jobs to use for the NN query in the point_to_precise computation

class densemaps.numpy.maps.KernelDenseDistMap(log_matrix, lse_row=None, lse_col=None)¶

Map represented by a row-normalized dense matrix obtained from an element-wise exponential.

The matrix is of size (N2, N1), and has values \(P_{ij} = \frac{1}{\sum_j \exp(D_{ij})} \exp(D_{ij})\) where \(D\) is some matrix

Only D has to be provided

Parameters:

log_matrix (np.ndarray) – (N2, N1) or (B, N2, N1), the matrix D
lse_row (np.ndarray, optional) – (N2,) or (B, N2). The logsumexp on rows
lse_col (np.ndarray) – (N1,) or (B, N1). The logsumexp on columns

to_dense()¶: Public alias for _to_dense(). Returns the (N2, N1) dense matrix.

pull_back(f)¶

Pull back a function \(f\). Four possibilities:

f is a function on S1, of shape (N1,), then the output is a function on S2, of shape (N2,)
f represents multiple function on S1, of shape (N1, p), then the output is a function on S2, of shape (N2, p)
f represents a batch multiple function on S1, of shape (B, N1, p), then the output is a function on S2, of shape (B, N2, p)

Note tht the case where f is a batch of a single function (B, N1) is not supported, and one should then use f[…, None]

Parameters:: f (np.ndarray) – (N1,), (N1, p) or (B, N1, p)
Returns:: f_pb – (N2,), (N2, p) or (B, N2, p)
Return type:: np.ndarray

get_nn()¶

Outputs the nearest neighbor map. The nearest neighbor map is the map that associates to each point of S2 the index of the closest point in S1. Simple argmax along the last dimension.

Returns:: nn_map – (N2,) on the representation
Return type:: np.ndarray

reverse()¶

Row-normalized reverse map, from \(S_1\) to \(S_2\).

This is not the literal matrix transpose (see mT): the reverse map is re-normalized so that its rows sum to 1, i.e. it is the row-normalized version of \(\Pi^\top\). Use this to get a valid (row-stochastic) map in the reverse direction.

Returns:: map_rev – Row-normalized reverse map
Return type:: KernelDenseDistMap

property mT¶

Literal matrix transpose \(\Pi^\top\) of the (dense, row-normalized) map.

Note

The transpose of a row-stochastic matrix is not row-stochastic. For a valid reverse map (rows summing to 1), use reverse() instead.

Returns:: map_t – Transpose map, wrapping the dense (N1, N2) matrix
Return type:: SparseMap

property shape¶

Shape of the map.

Returns:: shape – Depends on the representation
Return type:: tuple

class densemaps.numpy.maps.EmbKernelDenseDistMap(emb1, emb2, blur=None, normalize=False, normalize_emb=False, dist_type='sqdist')¶

Kernel Map, computed from embeddings.

Simple wrapper around KernelDenseDistMap.

Kernel has the form \(\exp\big(-\frac{s(x,y)}{2\sigma^2}\big)\), where \(s(x,y)\) is either: - the negative squared distance between the embeddings of x and y. - the (positive) inner product between the embeddings of x and y (potentially normalized).

Parameters:

emb1 (np.ndarray) – (N1, p) or (B, N1, p) embedding on first shape
emb2 (np.ndarray) – (N2, p) or (B, N2, p) embedding on second shape
blur (float) – Standard deviation of the Gaussian kernel.
normalize (bool) – Normalize the blur by the maximum distance between embedding points
normalize_emb (bool) – Normalize the embeddings.
dist_type (string) – {“sqdist”, “inner”} Type of score to use.