densemaps.torch.maps¶

Classes

`EmbKernelDenseDistMap`(emb1, emb2[, blur, ...])	Kernel Map, computed from embeddings.
`EmbP2PMap`(emb1, emb2)	Point to point map, computed from embeddings.
`EmbPreciseMap`(emb1, emb2, faces1[, clear_cache])	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.
`KernelDistMap`(emb1, emb2[, normalize, blur, ...])	Memory-Scalable Version of EmbKernelDenseDistMap
`P2PMap`(p2p_21[, n1])	Point to point map from a set S2 to a set S1.
`PointWiseMap`([tensor_names])	Root class representing a pointwise map.
`PreciseMap`(v2face_21, bary_coords, faces1)	Point to barycentric map from a set S2 to a surface S1.
`SparseMap`(map)	Map represented by a sparse matrix.

class densemaps.torch.maps.PointWiseMap(tensor_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\).

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

In torch, all maps can be represented in a batched way, with an additional dimension at the beginning of the tensor.

tensor_names¶

Names of the tensors stored in the object. Used to transfer to GPU.

Type:: list of str

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

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 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 (torch.Tensor) – (N1,), (N1, p) or (B, N1, p)
Returns:: f_pb – (N2,), (N2, p) or (B, N2, p)
Return type:: torch.Tensor

get_nn()¶

Ouptputs 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:: torch.Tensor

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.torch.maps.SparseMap(map)¶

Map represented by a sparse matrix.

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

Can actually represent a densemap too, but it’s not recommended.

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

property shape¶

Shape of the map.

Returns:: shape – returns (N2, N1) or (B, 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:: SparseMap

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 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 (torch.Tensor) – (N1,), (N1, p) or (B, N1, p)
Returns:: f_pb – (N2,), (N2, p) or (B, N2, p)
Return type:: torch.Tensor

class densemaps.torch.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 a tensor 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 (th.Tensor) – (n2,) or (B, n2)
n1 (int or None) – Number of points in S1. If None, n1 = p2p.max()+1

property n1¶

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

Returns:: n1
Return type:: int

property shape¶

Shape of the map.

Returns:: shape – return (n2,) or (B, n2)
Return type:: tuple

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 (torch.Tensor) – (N1,), (N1, p) or (B, N1, p)
Returns:: f_pb – (N2,), (N2, p) or (B, N2, p)
Return type:: torch.Tensor

get_nn()¶

Ouptputs 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:: torch.Tensor

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.torch.maps.PreciseMap(v2face_21, bary_coords, faces1)¶

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.

Note

Batched version is not supported yet.

Parameters:

v2face_21 (torch.Tensor) – (n2,) Indices of the faces of S1 closest to each point of S2.
bary_coords (torch.Tensor) – (n2, 3) Barycentric coordinates of the points of S2 in the faces of S1.
faces1 (torch.Tensor) – (N1, 3) All the Faces of S1.

property shape¶

Shape of the map.

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

pull_back(f)¶

Pull back f using the map T.

Parameters:¶

f : (N1,), (N1, p) or (B, N, p)

returns:: pull_back
rtype:: (N2, p) or (B, N2, p)

get_nn()¶

Ouptputs 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:: torch.Tensor

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.torch.maps.EmbP2PMap(emb1, emb2)¶

Point to point map, computed from embeddings.

Simple wrapper around P2PMap

Parameters:

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

class densemaps.torch.maps.EmbPreciseMap(emb1, emb2, faces1, clear_cache=True)¶

Point to barycentric map, computed from embeddings.

Simple wrapper around PreciseMap

Note

Batched version is not supported yet.

Parameters:

emb1 (torch.Tensor) – (N1, K)
emb2 (torch.Tensor) – (N2, K)
faces1 (torch.Tensor) – (N1, 3)
clear_cache (bool) – The projection somehow leaves lot of cache on the GPU, which should be cleared manually (slower than the projection itself…)

class densemaps.torch.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 (torch.Tensor) – (N2, N1) or (B, N2, N1), the matrix D
lse_row (torch.Tensor, optional) – (N2,) or (B, N2). The logsumexp on rows
lse_col (torch.Tensor) – (N1,) or (B, N1). The logsumexp on columns

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 (torch.Tensor) – (N1,), (N1, p) or (B, N1, p)
Returns:: f_pb – (N2,), (N2, p) or (B, N2, p)
Return type:: torch.Tensor

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:: torch.Tensor

property mT¶

Transposes the map.

Returns another KernelDenseDistMap object with the transposed matrix.

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

property shape¶

Shape of the map.

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

class densemaps.torch.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 (torch.Tensor) – (N1, p) or (B, N1, p) embedding on first shape
emb2 (torch.Tensor) – (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.

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

Memory-Scalable Version of EmbKernelDenseDistMap

Row normalized version fo the kernel map of 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 (torch.Tensor) – (N1, p) or (B, N1, p) embedding on first shape
emb2 (torch.Tensor) – (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.

property shape¶

Shape of the map.

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

get_pull_back_formula(dim)¶: B, N1, 1 -> B, N2, 1

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()¶

Ouptputs 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:: torch.Tensor

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