Embedding2d

class torch_geopooling.nn.Embedding2d(manifold: Tuple[int, int, int], exterior: Exterior | Tuple[float, float, float, float], padding: Tuple[int, int] = (0, 0))[source]

Retrieves spatial embeddings from a fixed-size lookup table based on 2D coordinates.

This module accepts a tensor of (x, y) coordinates and retrieves the corresponding spatial embeddings from a provided embedding matrix. The embeddings are selected based on the input coordinates, with an optional padding to include neighboring cells.

Parameters:

  • manifold – The size of the 2-dimensional embedding in a form (W, H, N), where W is a width, H is a height, and N is a feature dimension of the embedding.

  • padding – The size of the neighborhood to query. Default is 0, meaning only the embedding for the exact input coordinate is retrieved.

  • exterior – The geometric boundary of the learning space, specified as a tuple (X, Y, W, H), where X and Y represent the origin, and W and H represent the width and height of the space, respectively.

Shape:

  • Input: \((*, 2)\), where 2 comprises x and y coordinates.

  • Output: \((*, X_{out}, Y_{out}, N)\), where * is the input shape, \(N = \text{manifold[2]}\), and

    \(X_{out} = \text{padding}[0] \times 2 + 1\)

    \(Y_{out} = \text{padding}[1] \times 2 + 1\)

Examples:

>>> # Create an embedding of EPSG:4326 rectangle into 1024x1024 embedding
>>> # with 3 features in each cell.
>>> embedding = nn.Embedding2d(
...     (1024, 1024, 3),
...     exterior=(-180.0, -90.0, 360.0, 180.0),
...     padding=(2, 2),
... )
>>> input = torch.rand((100, 2), dtype=torch.float64) * 60.0
>>> output = embedding(input)