Dataset sampling

Creating a dataset of points with associated signal values is handled by a PointSampler object.

PointSampler(geom_object, sampling_strategy, *field_generators)

The PointSampler class is responsible for generating a dataset of points to be fed to a neural implicit representation during training.

Parameters:

Name	Type	Description	Default
geom_object	Mesh	the input geometrical object around which points are sampled.	required
sampling_strategy	SamplingStrategy	the strategy to be used for sampling points (see Sampling Strategies)	required
*field_generators	FieldGenerator	the data to be computed at each sampled points (see Implicit Fields). Several fields can be provided for several signals to be computed. Defaults to None (no field will be generated).	()

sample(n_points, on_ratio=0.01)

Samples a given number of points according to the provided sampling strategy.

Parameters:

Name	Type	Description	Default
n_points	int	number of points to sample.	required
on_ratio	float	ratio of sampled points that are taken on the geometry rather than around it. Defaults to 0.01.	0.01

Returns:

Type	Description
	np.ndarray, Tuple(np.ndarray): An array of sampled points and an array of the field value at these points.

sample_geometry(n_points)

Samples a given number of points on the geometrical object provided.

Parameters:

Name	Type	Description	Default
n_points	int	number of points to sample	required

Returns:

Type	Description
ndarray	np.ndarray: array of sampled points

Point Sampling strategies

CombinedStrategy(strategies, weights=None, shuffle=True)

Bases: SamplingStrategy

Combines different sampling strategies into one.

Parameters:

Name	Type	Description	Default
strategies	list	list of SamplingStrategy objects to call for sampling.	required
weights	list	relative weights of the sampling strategies. Weights [1,2] means that twice as many points will be sampled from the second strategy. If not provided, sampling is uniform. Defaults to None.	None
shuffle	bool	Whether to shuffle the output points	True

Raises:

Type	Description
Exception	Fails if weights are not all positive.

Gaussian(geom_object, stdv)

Bases: SamplingStrategy

Multivariate Gaussian sampling with zero mean.

Parameters:

Name	Type	Description	Default
geom_object	Mesh	geometry to sample. Only the dim attribute is accessed.	required
stdv	float	Standard variation of the Gaussian distribution.	required

NearGeometryGaussian(geom_object, stdv=0.01)

Bases: SamplingStrategy

Sample points around a given object by first sampling points on the object and add a Gaussian noise.

Parameters:

Name	Type	Description	Default
geom_object	Mesh	geometry to sample.	required
stdv	float	Standard variation of the Gaussian distribution. Defaults to 1e-2.	0.01

Raises:

Type	Description
Exception	Fails if the function is unable to sample the given geometrical object.

UniformBox(geom_object, domain=None)

Bases: SamplingStrategy

Uniform sampling in an axis-aligned bounding box.

Parameters:

Name	Type	Description	Default
geom_object	Mesh	geometry to sample. Only the dim attribute is accessed.	required
domain	AABB	bounding box to consider for sampling. If not provided, will take [-1.5, 1.5]^n as default. Defaults to None.	None

Creating your own custom strategy

A custom strategy can be defined by writing a custom class that inherits from the abstract base class SamplingStrategy:

from implicitlab.data.sampling_strategies import SamplingStrategy

class MyCustomSamplingStrategy(SamplingStrategy):

    def __init__(self, *args):
        # Implement the initialization of the data needed for your strategy here

    def sample(self, n_pts: int) -> np.ndarray:
        # Implement your sampling here

Examples of use

"""
Define a point sampler for the signed distance to the geometry, with a combined strategy
"""
import implicitlab as IL
from implicilab import sampling_strategies as strats

# The defined sampling strategy : 
# 2/3 of the points are taken in a uniform box (by default [-1, 1]^d)
# around the shape. 1/3 of the points are computed as a sampling on 
# the geometry plus some Gaussian noise of standard deviation 0.1
sampling_strat = strats.CombinedStrategy([
    strats.UniformBox(geometry),
    strats.NearGeometryGaussian(geometry, stdv=0.1)
], [2., 1.])

# The signal to compute for each point is the signed distance to the geometry
field = IL.fields.Distance(geometry, signed=True, square=False)

# The sampler is created
sampler = IL.PointSampler(
    geometry, # some loaded geometry
    sampling_strat, # the strategy
    field # the field
)

# Sample 10k points
points, sdfs = sampler.sample(10_000) 

"""
Define a point sampler with two different fields (occupancy and nearest point)"""

import implicitlab as IL
from implicilab import sampling_strategies as strats

sampler = IL.PointSampler(
    geometry, # some loaded geometry
    IL.sampling_strategy.UniformBox(geometry), # the sampling strategy
    IL.fields.Occupancy(geometry, v_in=-1, v_out=1, v_on=-1), # the occupancy field
    IL.fields.Nearest(geometry) # the nearest point field
)
points, field_values = sampler.sampler(10_000) 

This example wil sample 10k points uniformly in a bounding box around the geometry object. It returns the points and an occupancy value for each point.