Generating Coordinates

To keep a simple, uniform, consistent API; everything in TorchSample operates off of normalized coordinates in range [-1, 1], unless explicitly stated otherwise.

Similarly, all coordinates are always in order (x, y, ...). If the shape of a space is given, it is always in order (x, y, ...). For example, the shape of a 4D tensor is typically expressed as (b, c, h, w). So, if a function needs the query space shape, the argument would be (w, h) since w is associated with x and h is associated with y.

Random Coordinates

To generate random coordinates, use ts.coord.rand:

coords = ts.coord.rand(16, 4096, 2, device="cuda")
assert coords.shape == (16, 4096, 2)

To generate coordinates that fall exactly on pixels for a given resolution, you can use ts.coord.randint. Despite the name, the returned coordinates are still normalized and in range [-1. 1].

image = torch.rand(16, 3, 480, 640)
coords = ts.coord.randint(16, 4096, (640, 480))

Similar to numpy, TorchSample offers convenience functions ending in _like that accepts a 4D or 5D tensor so that the caller doesn’t have to juggle around shape.

image = torch.rand(16, 3, 480, 640)
coords = ts.coord.randint_like(4096, image)  # (16, 4096, 2)

Comprehensive Coordinates

During inference time, its common to want to generate coordinates that comprehensively query an entire space.

image = torch.random
coords = ts.coord.full(1, (640, 480))  # (1, 480, 640, 2)

Or, create comprehensive coordinates that match a given tensor:

image = torch.rand(16, 3, 480, 640)
coords = ts.coord.full_like(image)  # (16, 480, 640, 2)

Helpers

To go back-and-forth between normalized and unnormalized coordinates, the helper functions ts.coord.normalize and ts.coord.unnormalize are available.

coords = ts.coord.rand(16, 4096, 2)  # range [-1, 1]
# xrange [0, 639];  yrange [0, 479]
unnormalized_coords = ts.coord.unnormalize(coords, (640, 480))
renormalized_coords = ts.coord.normalize(coords, (640, 480))
assert_close(coords, renormalized_coords)