densemaps.numpy¶

NumPy/SciPy backend for densemaps (CPU only, no PyTorch required).

class densemaps.numpy.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.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.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.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.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.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.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.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.

densemaps.numpy.knn_query(X, Y, k=1, return_distance=False, n_jobs=1)¶

Query nearest neighbors.

Parameters:

X (np.ndarray) – (N1,p) or (B, N1, p) first collection
Y (np.ndarray) – (N2,p) or (B, N2, p) second collection
k (int) – number of neighbors to look for
return_distance (bool) – hether to return the nearest neighbor distance
n_jobs (int) – number of parallel jobs. Set to -1 to use all processes

Returns:

dists (np.ndarray, optional) – (n2,k) or (n2,) if k=1 (with optional first batch dimension)- ONLY if return_distance is False. Nearest neighbor distance.
matches (np.ndarray) – (n2,k) or (n2,) if k=1 (with optional first batch dimension)- nearest neighbor

densemaps.numpy.compute_sqdistmat(X, Y, normalized=False)¶

Computes the pairwise squared Euclidean distance matrix between two sets of points X and Y.

Parameters:

X (np.ndarray) – The first set of points, of shape (N, D) or (B, N, D).
Y (np.ndarray) – The second set of points, of shape (M, D) or (B, M, D).
normalized (bool) – Whether the points are normalized to have unit norm.

Returns:

distmat – The pairwise squared Euclidean distance matrix between X and Y, of shape (N, M) or (B, N, M).

Return type:

np.ndarray

densemaps.numpy.nn_query_precise_np(vert_emb, faces, points_emb, return_dist=False, batch_size=None, n_jobs=1)¶

Project a pointcloud on a p-dimensional mesh.

Parameters:

vert_emb – (n1, p) coordinates of the mesh vertices
faces – (m1, 3) faces of the mesh defined as indices of vertices
points_emb – (n2, p) coordinates of the pointcloud
return_dist – whether to return the distance to the nearest vertex
batch_size (int, optional) – if precompute_dmin is False, projects batches of points on the surface
n_jobs (int) – number of parallel process for nearest neighbor precomputation

Returns:

face_match (np.ndarray) – (n2,) - indices of the face assigned to each point
bary_coord (np.ndarray) – (n2,3) - barycentric coordinates of each point within the face
dists (np.ndarray) – (n2,) - distance to the nearest vertex

densemaps.numpy.project_pc_to_triangles(vert_emb, faces, points_emb, precompute_dmin=True, batch_size=None, n_jobs=1, return_sparse=False, verbose=False)¶

Project a pointcloud on a set of triangles in p-dimension. Projection is defined as barycentric coordinates on one of the triangle. Line i for the output has 3 non-zero values at indices j,k and l of the vertices of the triangle point i zas projected on.

Parameters:

vert_emb (np.ndarray) – (n1, p) coordinates of the mesh vertices
faces (np.ndarray) – (m1, 3) faces of the mesh defined as indices of vertices
points_emb (np.ndarray) – (n2, p) coordinates of the pointcloud
precompute_dmin (bool) – Whether to precompute all the values of delta_min. Faster but heavier in memory.
batch_size (int, optional) – If precompute_dmin is False, projects batches of points on the surface
n_jobs (int) – number of parallel process for nearest neighbor precomputation
return_sparse (bool) – Whether to return a sparse matrix instead of the face_match and barycentric coordinate

Returns:

precise_map (sparse.csrmatrix, optional) – (n2,n1) - precise point to point map. ONLY if return_sparse is True
face_match (np.ndarray) – (n2,) - indices of the face assigned to each point. ONLY if return_sparse is False
bary_coord (np.ndarray) – (n2,3) - barycentric coordinates of each point within the face. ONLY if return_sparse is False

densemaps.numpy.barycentric_to_precise(faces, face_match, bary_coord, n_vertices=None)¶

Transforms set of barycentric coordinates into a precise map

Parameters:

faces – (m,3) - Set of faces defined by index of vertices.
face_match – (n2,) - indices of the face assigned to each point
bary_coord – (n2,3) - barycentric coordinates of each point within the face
n_vertices (int) – number of vertices in the target mesh (on which faces are defined)

Returns:

precise_map – (n2,n1) - precise point to point map

Return type:

scipy.sparse.csr_matrix

Modules

`maps`
`nn_utils`
`point_to_triangle`