pynif3d.sampling¶

class pynif3d.sampling.AllPixelSampler(height, width)¶

Bases: torch.nn.modules.module.Module

The function that is used to sample all the elements of the given input 2D array. This function simply flattens a 2D array based on the [y, x] coordinates and returns each pixel as result.

Usage:

sampler = AllPixelSampler(image_height, image_width)
sampled_data = sampler(rays_directions=rays_d, rays_origins=rays_o)

rays_d = sampled_data["ray_directions"]
rays_o = sampled_data["ray_origins"]

Parameters

height (int) – The height of the 2D array to be sampled. Positive integer.
width (int) – The width of the 2D array to be sampled. Positive integer.

forward(image=None, **kwargs)¶

Parameters: image (torch.Tensor) – (Optional) The input 2D array to be sampled. Its shape is (1, 3, image_height, image_width).
Returns: Dictionary containing the sampled colors (RGB values) and pixel coordinates. The sampled colors are represented as torch.Tensor with shape (n_pixels, 3), while the sampled coordinates are represented as a torch.Tensor with shape (n_pixels, 2).
Return type: dict

training: bool¶

class pynif3d.sampling.FeatureSampler2D(sample_mode='bilinear', padding=0.1)¶

Bases: torch.nn.modules.module.Module

Initializes internal Module state, shared by both nn.Module and ScriptModule.

forward(points, plane_features)¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

training: bool¶

class pynif3d.sampling.FeatureSampler3D(sample_mode='bilinear', padding=0.1)¶

Bases: torch.nn.modules.module.Module

Initializes internal Module state, shared by both nn.Module and ScriptModule.

forward(points, plane_features)¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

training: bool¶

class pynif3d.sampling.RandomPixelSampler(height, width)¶

Bases: torch.nn.modules.module.Module

Randomly samples N elements from a given 2D array as input.

Parameters

height (int) – Positive integer defining the height of the 2D array to be sampled.
width (int) – Positive integer defining the width of the 2D array to be sampled.

Usage:

sampler = RandomPixelSampler(image_height, image_width)
sampled_data = sampler(rays_directions=rays_d, rays_origins=rays_o)

rays_d = sampled_data["ray_directions"]
rays_o = sampled_data["ray_origins"]

forward(n_sample, **kwargs)¶

Parameters

n_sample (int) – Positive integer defining the number of samples to be queried.
kwargs (dict) – The (key, value) pairs for multiple values to be sampled at once.

Returns

Dictionary containing the same (key, value) pairs as **kwargs. It also contains the random sampling locations.

Return type

dict

training: bool¶

class pynif3d.sampling.SecantRaySampler(sdf_model)¶

Bases: torch.nn.modules.module.Module

Samples the ray in a given range, computes the SDF values for the sampled points and runs the secant method for the rays which have sign transition. Returns the resulting points and their corresponding SDF values.

:: note:

For more information about the secant method, please check the following page: https://en.wikipedia.org/wiki/Secant_method

Usage:

# Assume an SDF model (torch.nn.Module) is given.
sampler = SecantRaySampler(sdf_model)
points, z_vals, mask = sampler(
    ray_directions, ray_origins, ray_mask, zs_min, zs_max
)

Parameters: sdf_model (instance) – Instance of an SDF model. When calling the forward method with some input points, it needs to return a dictionary containing the SDF values corresponding to those points, as an “sdf_vals” key/value pair.

forward(rays_d, rays_o, rays_m, zs_min, zs_max, **kwargs)¶

Parameters

rays_d (torch.Tensor) – Tensor containing the ray directions. Its shape is (n_rays, 3).
rays_o (torch.Tensor) – Tensor containing the ray origins. Its shape is (n_rays, 3).
rays_m (torch.Tensor) – Boolean tensor containing the object mask for the given rays. If rays_d[i] intersects the object, rays_m[i] is marked as True, otherwise as False. Its shape is (n_rays,).
zs_min (torch.Tensor) – Tensor containing the minimum Z values of the points that are sampled along the ray. Its shape is (n_rays,).
zs_max (torch.Tensor) – Tensor containing the maximum Z values of the points that are sampled along the ray. Its shape is (n_rays,).
kwargs (dict) –
- n_samples (int): The number of points that are sampled along the rays. Default value is 100.
- chunk_size (int): The size of the chunk of points that is passed to the SDF model. Default value is 10000.

Returns

Tuple containing the secant points (as a torch.Tensor with shape (n_rays, 3)), corresponding Z values (as a torch.Tensor with shape (n_rays,)) and a mask (as a torch.Tensor with shape (n_rays,)) specifying which points were successfully found by the secant method to be roots of the optimization function.

Return type

tuple

training: bool¶

class pynif3d.sampling.UniformRaySampler(near, far, n_samples, is_perturb=True)¶

Bases: torch.nn.modules.module.Module

Randomly samples a ray. Takes as input a ray origin and direction, near, far, the number of points to sample and generates point coordinates across each given ray.

Usage:

near = 0.1
far = 5.0
n_samples = 1000

sampler = UniformRaySampler(near, far, n_samples)
points, z_vals = sampler(ray_directions, ray_origins)

Parameters

near (float) – Minimum depth value corresponding to the sampled points.
far (float) – Maximum depth value corresponding to the sampled points.
n_samples (int) – Number of sampled points along the ray.
is_perturb (bool) – Boolean flag indicating whether to perturb the sampled points (True) or not (False). Default value is True.

forward(rays_d, rays_o)¶

Parameters

rays_d (torch.Tensor) – Tensor containing the ray directions. Its shape is (n_ray_samples, 3) or (batch_size, n_ray_samples, 3).
rays_o (torch.Tensor) – Tensor containing the ray origins. Its shape is (n_ray_samples, 3) or (batch_size, n_ray_samples, 3).

Returns

Tuple containing the sampled points and the corresponding Z values.

Return type

tuple

training: bool¶

class pynif3d.sampling.WeightedRaySampler(near, far, n_sample, eps=1e-05)¶

Bases: torch.nn.modules.module.Module

Neural implicit model-based importance sampling function for rays which is used in the NeRF paper. For details, please check https://arxiv.org/abs/2003.08934.

Usage:

near = 0.1
far = 5.0
n_samples = 1000

sampler = WeightedRaySampler(near, far, n_samples)
points, z_vals = sampler(ray_directions, ray_origins, z_vals, weights)

Parameters

near (float) – Minimum depth value corresponding to the sampled points.
far (float) – Maximum depth value corresponding to the sampled points.
n_sample (int) – Number of sampled points along the ray.
eps (float) – Epsilon that is added to the weights, in order to avoid zero values. Default value is 1e-5.

forward(rays_d, rays_o, z_vals, weights, **kwargs)¶

Parameters

rays_d (torch.Tensor) – Tensor containing ray directions. Its shape is (batch_size, n_rays, 3).
rays_o (torch.Tensor) – Tensor containing ray origins. Its shape is (batch_size, n_rays, 3).
z_vals (torch.Tensor) – Tensor containing Z values. Its shape is (n_rays, n_samples_per_ray,).
weights (torch.Tensor) – Tensor containing the sampling weights. Its shape is (batch_size, n_rays, n_samples_per_ray).
kwargs (dict) –
- is_deterministic (bool): (Optional) Boolean flag indicating whether to sample the rays in a deterministic manner (True) or not (False). Default is False.

Returns

Tuple containing the sampled points and Z values.

Return type

tuple

sample_pdf(bins, weights, is_deterministic=False)¶

training: bool¶