DeepSDFStruct.sdf_primitives#

Primitive SDF Shapes#

This module provides basic geometric primitive SDFs that can be used as building blocks for more complex geometries. All primitives inherit from SDFBase and can be combined using boolean operations.

Available Primitives#

  • SphereSDF: Sphere with specified center and radius

  • CylinderSDF: Infinite cylinder along a coordinate axis

  • TorusSDF: Torus with major and minor radii

  • PlaneSDF: Half-space defined by a point and normal vector

  • CornerSpheresSDF: Cube with spherical cutouts at corners

  • CrossMsSDF: Cross-shaped structure (intersection of three cylinders)

  • RoundedBoxSDF: 3D axis-aligned box with rounded corners

  • WireframeBoxSDF: 3D wireframe box SDF

  • CapsuleSDF: SDF for a capsule (a line segment with a radius)

  • EllipsoidSDF: SDF for an ellipsoid

  • PyramidSDF: SDF for a pyramid

All primitives support PyTorch’s automatic differentiation and can be used in optimization workflows.

Classes

BoxSDF(center, extents)

Signed distance function for a 3D axis-aligned box.

CappedConeSDF(point_a, point_b, ra, rb)

Signed distance function for a finite cone with exact end caps.

CapsuleSDF(point_a, point_b, radius)

SDF for a capsule (a line segment with a radius).

CircleSDF(center, radius)

SDF for a 2D circle.

ConeSDF(apexpoint, axis, radius, height)

Signed distance function for a finite cone.

CornerSpheresSDF(radius[, limit])

Signed distance function for a cube with spherical cutouts at the corners.

CrossMsSDF(radius)

Signed distance function for a cross-shaped structure.

CylinderSDF(point_a, point_b, radius)

Signed distance function for a finite cylinder with exact end caps.

DodecahedronSDF([r])

SDF for a regular dodecahedron.

EllipsoidSDF(center, extents)

SDF for an ellipsoid.

EquilateralTriangleSDF([size])

SDF for a regular equilateral triangle.

HexagonSDF([size])

SDF for a regular hexagon.

IcosahedronSDF([r])

SDF for a regular icosahedron.

LineSDF(normal, point)

SDF for a 2D line (infinite line defined by normal vector and point).

OctahedronSDF([r])

SDF for a regular octahedron.

PlaneSDF(point, normal)

Signed distance function for a half-space defined by a point and normal vector.

PolygonSDF(vertices)

SDF for a general convex polygon defined by vertices.

PyramidSDF(height)

SDF for a pyramid.

RectangleSDF(center, extents)

SDF for a 2D rectangle with center and extents.

RoundedBoxSDF(center, extents, radius)

3D axis-aligned box with rounded corners.

RoundedConeSDF(r1, r2, h)

SDF for a cone with smooth rounded transitions.

RoundedCylinderSDF(ra, rb, h)

SDF for a cylinder with smooth rounded transitions.

RoundedRectangleSDF(center, extents, radius)

SDF for a 2D rectangle with rounded corners.

SlabSDF([x0, y0, z0, x1, y1, z1])

SDF for a slab (clipping box defined by axis-aligned planes).

SphereSDF(center, radius)

Signed distance function for a sphere.

TetrahedronSDF([r])

SDF for a regular tetrahedron.

TorusSDF(center, axis, major_radius, ...)

Signed distance function for a torus (doughnut shape).

WireframeBoxSDF(center, extents, thickness)

3D wireframe box SDF.
class DeepSDFStruct.sdf_primitives.BoxSDF(center, extents)#

Bases: DeepSDFStruct.SDF.SDFBase

Signed distance function for a 3D axis-aligned box.

The box is defined by its center point and extents (full widths) along each axis. Both center and extents are trainable torch parameters.

Parameters:

  • center (array-like of shape (3,)) – Center point of the box in 3D space.

  • extents (array-like of shape (3,)) – Full widths of the box along x, y, z axes.

Examples

>>> # Box centered at origin with dimensions 2x1x1
>>> BoxSDF(center=[0, 0, 0], extents=[2.0, 1.0, 1.0])
>>>
>>> # Elongated box in x-direction
>>> BoxSDF(center=[1, 0, 0], extents=[3.0, 0.5, 0.5])
class DeepSDFStruct.sdf_primitives.CappedConeSDF(point_a, point_b, ra, rb)#

Bases: DeepSDFStruct.SDF.SDFBase

Signed distance function for a finite cone with exact end caps.

Creates a cone frustum (or full cone if rb=0) defined by two endpoints and radii at each end. The cone has flat end caps at both ends.

Parameters:

  • point_a (array-like of shape (3,)) – First endpoint of the cone axis (base center).

  • point_b (array-like of shape (3,)) – Second endpoint of the cone axis (top center).

  • ra (float) – Radius at point_a (base radius). Must be non-negative.

  • rb (float) – Radius at point_b (top radius). Use 0 for a sharp cone tip.

Examples

>>> # Cone from (0,0,0) to (0,0,2) with base radius 0.5 and sharp tip
>>> CappedConeSDF(point_a=[0, 0, 0], point_b=[0, 0, 2], ra=0.5, rb=0.0)
>>>
>>> # Cone frustum with radii at both ends
>>> CappedConeSDF(point_a=[0, 0, 0], point_b=[0, 0, 1], ra=0.3, rb=0.1)

Notes

  • The cone axis is the line segment from point_a to point_b

  • ra and rb control the radii at each end independently

  • Set rb=0 for a cone with a sharp tip

  • Set ra=rb for a cylinder (use CylinderSDF instead for better accuracy)

class DeepSDFStruct.sdf_primitives.CapsuleSDF(point_a, point_b, radius)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a capsule (a line segment with a radius).

class DeepSDFStruct.sdf_primitives.CircleSDF(center, radius)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a 2D circle.

class DeepSDFStruct.sdf_primitives.ConeSDF(apexpoint, axis, radius, height)#

Bases: DeepSDFStruct.SDF.SDFBase

Signed distance function for a finite cone.

The cone is defined by: - apex point - axis direction - height - base radius

Parameters:

  • apexpoint (array-like of shape (3,)) – Apex position of the cone.

  • axis (array-like of shape (3,)) – Direction vector of the cone axis.

  • radius (float) – Radius at the base of the cone.

  • height (float) – Height of the cone from apex to base.

Example

>>> cone = ConeSDF(apexpoint=[0,0,0], axis=[0,1,0], radius=1.0, height=2.0)
class DeepSDFStruct.sdf_primitives.CornerSpheresSDF(radius, limit=1.0)#

Bases: DeepSDFStruct.SDF.SDFBase

Signed distance function for a cube with spherical cutouts at the corners.

Creates a cube with rounded corners by subtracting spheres from each of the 8 corners. The result is a cube-like shape with smooth corner transitions.

Parameters:

  • radius (float) – Radius of the spherical cutouts at each corner.

  • limit (float, default 1.0) – Half-size of the cube (distance from center to each face).

Examples

>>> from DeepSDFStruct.sdf_primitives import CornerSpheresSDF
>>> import torch
>>>
>>> corner_spheres = CornerSpheresSDF(radius=0.3, limit=1.0)
>>> points = torch.tensor([[0.0, 0.0, 0.0], [1.0, 1.0, 1.0]])
>>> distances = corner_spheres(points)
class DeepSDFStruct.sdf_primitives.CrossMsSDF(radius)#

Bases: DeepSDFStruct.SDF.SDFBase

Signed distance function for a cross-shaped structure.

Creates a 3D cross by computing the intersection of three cylinders aligned along the x, y, and z axes. The result is a symmetric cross-like structure centered at the origin.

Parameters:

radius (float) – Radius of each cylinder forming the cross.

Examples

>>> from DeepSDFStruct.sdf_primitives import CrossMsSDF
>>> import torch
>>>
>>> cross = CrossMsSDF(radius=0.2)
>>> points = torch.tensor([[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]])
>>> distances = cross(points)
class DeepSDFStruct.sdf_primitives.CylinderSDF(point_a, point_b, radius)#

Bases: DeepSDFStruct.SDF.SDFBase

Signed distance function for a finite cylinder with exact end caps.

Creates a cylinder defined by two endpoints and a radius.

Parameters:

  • point_a (array-like of shape (3,)) – First endpoint of the cylinder’s axis.

  • point_b (array-like of shape (3,)) – Second endpoint of the cylinder’s axis.

  • radius (float) – Radius of the cylinder.

Examples

>>> # Cylinder along z-axis from -1 to 1 with radius 0.5
>>> CylinderSDF(point_a=[0, 0, -1], point_b=[0, 0, 1], radius=0.5)
>>>
>>> # Cylinder along x-axis
>>> CylinderSDF(point_a=[-1, 0, 0], point_b=[1, 0, 0], radius=0.3)
>>>
>>> # Diagonal cylinder
>>> CylinderSDF(point_a=[0, 0, 0], point_b=[1, 1, 1], radius=0.2)
class DeepSDFStruct.sdf_primitives.DodecahedronSDF(r=1.0)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a regular dodecahedron.

class DeepSDFStruct.sdf_primitives.EllipsoidSDF(center, extents)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for an ellipsoid.

class DeepSDFStruct.sdf_primitives.EquilateralTriangleSDF(size=1.0)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a regular equilateral triangle.

class DeepSDFStruct.sdf_primitives.HexagonSDF(size=1.0)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a regular hexagon.

class DeepSDFStruct.sdf_primitives.IcosahedronSDF(r=1.0)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a regular icosahedron.

class DeepSDFStruct.sdf_primitives.LineSDF(normal, point)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a 2D line (infinite line defined by normal vector and point).

class DeepSDFStruct.sdf_primitives.OctahedronSDF(r=1.0)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a regular octahedron.

class DeepSDFStruct.sdf_primitives.PlaneSDF(point, normal)#

Bases: DeepSDFStruct.SDF.SDFBase

Signed distance function for a half-space defined by a point and normal vector.

Computes the signed distance from query points to a plane. The distance is negative on the side the normal points toward, zero on the plane, and positive on the opposite side.

Parameters:

  • point (array-like of shape (3,)) – A point on the plane.

  • normal (array-like of shape (3,)) – Normal vector defining the plane orientation (will be normalized).

Examples

>>> from DeepSDFStruct.sdf_primitives import PlaneSDF
>>> import torch
>>>
>>> # Plane at z=0 with normal pointing up
>>> plane = PlaneSDF(point=[0, 0, 0], normal=[0, 0, 1])
>>> points = torch.tensor([[0.0, 0.0, 0.0], [0.0, 0.0, 1.0], [0.0, 0.0, -1.0]])
>>> distances = plane(points)
>>> print(distances)  # [0.0, 1.0, -1.0]
class DeepSDFStruct.sdf_primitives.PolygonSDF(vertices)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a general convex polygon defined by vertices.

class DeepSDFStruct.sdf_primitives.PyramidSDF(height)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a pyramid.

class DeepSDFStruct.sdf_primitives.RectangleSDF(center, extents)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a 2D rectangle with center and extents.

class DeepSDFStruct.sdf_primitives.RoundedBoxSDF(center, extents, radius)#

Bases: DeepSDFStruct.SDF.SDFBase

3D axis-aligned box with rounded corners.

class DeepSDFStruct.sdf_primitives.RoundedConeSDF(r1, r2, h)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a cone with smooth rounded transitions.

class DeepSDFStruct.sdf_primitives.RoundedCylinderSDF(ra, rb, h)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a cylinder with smooth rounded transitions.

class DeepSDFStruct.sdf_primitives.RoundedRectangleSDF(center, extents, radius)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a 2D rectangle with rounded corners.

class DeepSDFStruct.sdf_primitives.SlabSDF(x0=None, y0=None, z0=None, x1=None, y1=None, z1=None)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a slab (clipping box defined by axis-aligned planes).

class DeepSDFStruct.sdf_primitives.SphereSDF(center, radius)#

Bases: DeepSDFStruct.SDF.SDFBase

Signed distance function for a sphere.

Computes the signed distance from query points to a sphere surface. The distance is negative inside the sphere, zero on the surface, and positive outside.

Parameters:

  • center (array-like of shape (3,)) – Center point of the sphere in 3D space.

  • radius (float) – Radius of the sphere.

Examples

>>> # Sphere centered at origin with radius 0.5
>>> SphereSDF(center=[0, 0, 0], radius=0.5)
>>>
>>> # Sphere at different location with larger radius
>>> SphereSDF(center=[1, 0, 0], radius=1.0)
class DeepSDFStruct.sdf_primitives.TetrahedronSDF(r=1.0)#

Bases: DeepSDFStruct.SDF.SDFBase

SDF for a regular tetrahedron.

class DeepSDFStruct.sdf_primitives.TorusSDF(center, axis, major_radius, minor_radius)#

Bases: DeepSDFStruct.SDF.SDFBase

Signed distance function for a torus (doughnut shape).

Creates a torus defined by its center, orientation axis, and two radii. The torus is rotationally symmetric around the axis direction.

Parameters:

  • center (array-like of shape (3,)) – Center point of the torus in 3D space.

  • axis (array-like of shape (3,)) – Axis vector normal to the torus ring plane. The torus is rotationally symmetric around this axis. Will be normalized.

  • major_radius (float) – Distance from the center to the tube center (R). This is the radius of the ring itself. Must be positive.

  • minor_radius (float) – Radius of the tube cross-section (r). This is the thickness of the ring. Must be positive and typically less than major_radius.

Examples

>>> # Torus centered at origin, lying in XY plane (axis along Z)
>>> TorusSDF(center=[0, 0, 0], axis=[0, 0, 1], major_radius=1.0, minor_radius=0.2)
>>>
>>> # Tilted torus with axis at an angle
>>> TorusSDF(center=[0, 0, 0], axis=[1, 0, 1], major_radius=1.0, minor_radius=0.1)

Notes

  • The torus lies in a plane perpendicular to the axis vector

  • major_radius > minor_radius creates a ring torus (standard doughnut)

  • major_radius = minor_radius creates a horn torus (hole closes)

  • major_radius < minor_radius creates a self-intersecting spindle torus

  • All parameters are trainable for optimization

class DeepSDFStruct.sdf_primitives.WireframeBoxSDF(center, extents, thickness)#

Bases: DeepSDFStruct.SDF.SDFBase

3D wireframe box SDF.