DeepSDFStruct.sampling#

SDF Sampling and Dataset Generation#

This module provides tools for sampling points from SDF representations and generating datasets for training neural networks (DeepSDF models). It supports various sampling strategies to create well-distributed training data.

Key Features#

Sampling Strategies

  • Uniform sampling in a bounding box

  • Surface-focused sampling near the zero level set

  • Importance sampling based on SDF gradients

  • Sphere-based sampling patterns

  • Combined strategies for balanced datasets

Dataset Generation

  • Batch processing of multiple geometries

  • Automatic data normalization and standardization

  • Support for multiple geometry classes

  • Metadata tracking (version, sampling parameters)

  • Export to formats compatible with DeepSDF training

The module is designed to generate high-quality training data for implicit neural representations, with careful attention to sampling near surfaces where accurate reconstruction is most critical.

Classes#

SampledSDF

Container for sampled points and their SDF values, with utilities for splitting by sign and visualization.

DataSetInfo

TypedDict for dataset metadata (name, classes, sampling strategy, etc.).

Functions#

generate_dataset

Batch process multiple geometries to create a complete dataset.

sample_sdf_*

Various sampling strategies for different use cases.

Functions

augment_by_FFD(meshs[, n_control_points, ...])

Takes list of meshs and augments the meshs by applying a freeform deformation

move(t_mesh, new_center)

noisy_sample(t_mesh, std, count)

random_points(count)

random points in a unit sphere centered at (0, 0, 0)

random_points_cube(count, box_size)

random points in a cube with size box_size centered at (0, 0, 0)

random_sample_sdf(sdf, bounds, n_samples[, ...])

sample_mesh_surface(sdf, mesh, n_samples, stds)

Sample noisy points around a mesh surface and evaluate them with a signed distance function (SDF).

save_points_to_vtp(filename, neg, pos)

Save pos/neg SDF sample points as a VTU point cloud using vtkPolyData.

Classes

DataSetInfo

Metadata for a generated SDF dataset.

SDFSampler(outdir, splitdir, dataset_name[, ...])

SampledSDF(samples, distances)

Container for sampled SDF points and their distance values.

SphereParameters

Parameters defining a sampling sphere.
class DeepSDFStruct.sampling.DataSetInfo#

Bases: TypedDict

Metadata for a generated SDF dataset.

dataset_name#

Unique identifier for the dataset.

Type:

str

class_names#

Names of geometry classes in the dataset.

Type:

list of str

sampling_strategy#

Description of how points were sampled.

Type:

str

date_created#

ISO format timestamp of dataset creation.

Type:

str

stds#

Standard deviations used for normalization.

Type:

list of float

n_samples#

Number of sample points per geometry.

Type:

int

add_surface_samples#

Whether surface points were included.

Type:

bool

sdf_struct_version#

Version of DeepSDFStruct used to create the dataset.

Type:

str

add_surface_samples: bool#
class_names: list[str]#
dataset_name: str#
date_created: str#
n_samples: int#
sampling_strategy: str#
sdf_struct_version: str#
stds: list[float]#
class DeepSDFStruct.sampling.SDFSampler(outdir, splitdir, dataset_name, stds=[0.05, 0.025], overwrite_existing=False)#

Bases: object

add_class(geom_list, class_name, n_faces=100)#

Adds a geometry to the sampler object. Tries to transform inputs to trimesh data. In case the geometry is a spline object, the n_faces parameter determines the accuracy of the extracted mesh

Return type:

None

Parameters:

  • geom_list (list)

  • class_name (str)

get_meshs_from_folder(foldername, mesh_type)#

Reads all mesh files of a given type (extension) from a folder using meshio.

Parameters:

  • foldername (str) – Path to the folder containing the mesh files.

  • mesh_type (str) – Mesh file extension (e.g., ‘vtk’, ‘obj’, ‘stl’, ‘msh’, ‘xdmf’).

Returns:

A list of trimesh.Trimesh objects loaded from the folder.

Return type:

list[trimesh.Trimesh]

process_geometries(sampling_strategy='uniform', n_faces=100, n_samples=100000, add_surface_samples=True, also_save_vtk=False, also_save_mesh=True, scale=True, n_workers=0)#
Parameters:

n_samples (int)

write_json(json_fname)#
class DeepSDFStruct.sampling.SampledSDF(samples, distances)#

Bases: object

Container for sampled SDF points and their distance values.

This class stores point samples and their corresponding SDF values, providing utilities for data manipulation, splitting, and visualization.

Parameters:

  • samples (torch.Tensor) – Point coordinates of shape (N, 3).

  • distances (torch.Tensor) – SDF values at sample points of shape (N, 1).

samples#

The sampled point coordinates.

Type:

torch.Tensor

distances#

The SDF distance values.

Type:

torch.Tensor

split_pos_neg()#

Split into separate datasets for inside (negative) and outside (positive) points.

create_gus_plottable()#

Convert to gustaf Vertices for visualization.

stacked()#

Property returning concatenated samples and distances.

Examples

>>> import torch
>>> from DeepSDFStruct.sampling import SampledSDF
>>>
>>> points = torch.rand(100, 3)
>>> distances = torch.randn(100, 1)
>>> sampled = SampledSDF(points, distances)
>>>
>>> # Split by sign
>>> inside, outside = sampled.split_pos_neg()
>>> print(f"Inside points: {inside.samples.shape[0]}")
>>> print(f"Outside points: {outside.samples.shape[0]}")
create_gus_plottable()#

Create a gustaf Vertices object for visualization.

Returns:

Vertices with distance values stored as vertex data.

Return type:

gustaf.Vertices

distances: torch.Tensor#
samples: torch.Tensor#
split_pos_neg()#

Split samples into inside (negative) and outside (positive) points.

Returns:

  • pos (SampledSDF) – Samples with non-negative distances (outside or on surface).

  • neg (SampledSDF) – Samples with negative distances (inside geometry).

property stacked#

Concatenate samples and distances into a single tensor.

Returns:

Tensor of shape (N, 4) with [x, y, z, distance] per row.

Return type:

torch.Tensor

class DeepSDFStruct.sampling.SphereParameters#

Bases: TypedDict

Parameters defining a sampling sphere.

cx: float#
cy: float#
cz: float#
r: float#
DeepSDFStruct.sampling.augment_by_FFD(meshs, n_control_points=5, std_dev_fraction=0.05, n_transformations=10, save_meshs=False)#

Takes list of meshs and augments the meshs by applying a freeform deformation

Return type:

list[Trimesh]

Parameters:

  • meshs (list[trimesh.base.Trimesh])

  • n_control_points (int)

  • std_dev_fraction (float | None)

  • n_transformations (int)

DeepSDFStruct.sampling.move(t_mesh, new_center)#
DeepSDFStruct.sampling.noisy_sample(t_mesh, std, count)#
DeepSDFStruct.sampling.random_points(count)#

random points in a unit sphere centered at (0, 0, 0)

DeepSDFStruct.sampling.random_points_cube(count, box_size)#

random points in a cube with size box_size centered at (0, 0, 0)

DeepSDFStruct.sampling.random_sample_sdf(sdf, bounds, n_samples, type='uniform', device='cpu', dtype=torch.float32)#
DeepSDFStruct.sampling.sample_mesh_surface(sdf, mesh, n_samples, stds, device='cpu', dtype=torch.float32)#

Sample noisy points around a mesh surface and evaluate them with a signed distance function (SDF).

This function uses trimesh.sample to generate surface samples and perturbs them with Gaussian noise of varying standard deviations, and queries the SDF at those points.

Parameters:

  • sdf (SDFBase) – A callable SDF object that takes 3D points and returns signed distances.

  • mesh (trimesh.Trimesh) – A mesh object containing the vertices and faces.

  • n_samples (int) – Number of mesh vertices to sample

  • stds (list[float]) – Standard deviations for Gaussian noise added to sampled vertices. - Typical values: [0.05, 0.0015]. - Larger values spread samples farther from the surface; smaller values keep them closer.

  • device (str, optional) – Torch device to place tensors on (e.g., “cpu” or “cuda”).

  • dtype (torch.dtype, optional) – Data type for generated tensors (default: torch.float32).

Returns:

An object containing:

  • samples (torch.Tensor): The perturbed sample points of shape (n_samples * len(stds), 3).

  • distances (torch.Tensor): The corresponding SDF values at those sample points.

Return type:

SampledSDF

DeepSDFStruct.sampling.save_points_to_vtp(filename, neg, pos)#

Save pos/neg SDF sample points as a VTU point cloud using vtkPolyData. Each point has an SDF scalar value.