VoxelMeshSDF¶

Inherits: Resource

Signed distance field of a mesh as voxels.

Description:¶

This resource can be used to bake a mesh into a signed distance field (SDF). The data is stored as an internal voxel buffer. This can then be used as a shape or brush in voxel-based operations.

Note: if you can, prefer using procedural shapes (like sphere or box) for better quality and performance. While versatile, VoxelMeshSDF it is more expensive to use and currently has lower quality compared to procedural equivalents.

Note 2: not all meshes can be baked. Best meshes should be manifold and represent a closed shape, with clear inside and outside.

Properties:¶

Type	Name	Default
Dictionary	_data	{}
BakeMode	bake_mode	BAKE_MODE_ACCURATE_PARTITIONED (1)
bool	boundary_sign_fix_enabled	true
int	cell_count	64
float	margin_ratio	0.25
Mesh	mesh
int	partition_subdiv	32

Methods:¶

Return	Signature
void	bake ( )
void	bake_async ( SceneTree scene_tree )
Array	debug_check_sdf ( Mesh mesh )
AABB	get_aabb ( ) const
VoxelBuffer	get_voxel_buffer ( ) const
bool	is_baked ( ) const
bool	is_baking ( ) const

Signals:¶

baked( )¶

Emitted when asynchronous baking is complete.

Enumerations:¶

enum BakeMode:

• BAKE_MODE_ACCURATE_NAIVE = 0 --- Checks every triangle from every cell to find the closest distances. It tries to be accurate, but is much slower than other techniques. The mesh must be closed, otherwise the SDF will contain errors. Signs are calculated by getting the closest triangle and checking which side of the triangle the center of the cell is.
• BAKE_MODE_ACCURATE_PARTITIONED = 1 --- Similar to the naive method, but subdivides space into partitions in order to more easily skip triangles that don't need to be checked. Faster than the naive method, but still relatively slow.
• BAKE_MODE_APPROX_INTERP = 2 --- Experimental method subdividing space in 4x4x4 cells, and skipping SDF calculations by interpolating 8 corners instead if no triangles are present in those cells. Faster than the naive method, but not particularly interesting. Might be removed.
• BAKE_MODE_APPROX_FLOODFILL = 3 --- Approximates the SDF by calculating a thin "hull" of accurate values near triangles, then propagates those values with a 26-way floodfill. Signs are calculated only on the initial hull by doing several raycasts from the center of each cell: if the ray hits a backface, the cell is assumed to be inside. Otherwise, it is assumed to be outside. Signs are propagated as part of the floodfill. While technically not accurate, it is currently the fastest method and results are often good enough.
• BAKE_MODE_COUNT = 4 --- How many baking modes there are.

Property Descriptions¶

Dictionary _data = {}¶

(This property has no documentation)

BakeMode bake_mode = BAKE_MODE_ACCURATE_PARTITIONED (1)¶

Selects the algorithm that will be used to compute SDF from the mesh.

bool boundary_sign_fix_enabled = true¶

Some algorithms might fail to properly compute the sign of distances on their own. Usually outside the shape has positive sign, and inside the shape has negative sign. Errors can cause the wrong sign to "leak" and propagate outside the shape.

This option attempts to fix this when it happens by assuming that the border of the baked region is always outside, and propagates positive signs inwards to ensure no negative signs leak.

int cell_count = 64¶

Controls the resolution of the baked SDF, proportionally to one side of the 3D voxel buffer. Higher increases quality, but is slower to bake and uses more memory.

float margin_ratio = 0.25¶

Controls the addition of extra space around the mesh's baking area.

Proper SDF buffers should have some margin in order to capture outside gradients. Without margin, the outside could appear cutoff or blocky when remeshed.

This property adds margin based on a ratio of the size of the mesh. For example, if the mesh is 100 units wide, a margin of 0.1 will add 10 extra units of space around it.

Mesh mesh¶

Mesh that will be baked when calling the bake function, or when pressing the Bake button in the editor.

Setting this property back to null will not erase the baked result, so you don't need the original mesh to be loaded in order to use the SDF.

int partition_subdiv = 32¶

Controls how many subdivisions to use across the baking area when using the BAKE_MODE_ACCURATE_PARTITIONED and BAKE_MODE_APPROX_FLOODFILL modes.

When using BAKE_MODE_ACCURATE_PARTITIONED, that value may be proportionally adjusted based on the amount of triangles the mesh has, due to an imperfection of the algorithm. If the mesh has few triangles, lower values will perform better. If it has a lot of small triangles, higher values will perform better. However, if triangles are large or few and the value is big, this will also potentially create artifacts.

Method Descriptions¶

void bake( )¶

Bakes the SDF on the calling thread, using the currently assigned mesh. Might cause the game to stall if done on the main thread.

void bake_async( SceneTree scene_tree )¶

Bakes the SDF on a separate thread, using the currently assigned mesh. See also is_baking, is_baked and VoxelMeshSDF.baked.

Array debug_check_sdf( Mesh mesh )¶

Experimental.

Runs some checks to verify if the baked SDF contains errors. The mesh to pass should be the mesh that was used for baking.

If there are errors, the returned array will contain information about up to 2 cells of the buffer containing wrong values, in the following format:

[
    cell0_position: Vector3,
    cell0_triangle_v0: Vector3,
    cell0_triangle_v1: Vector3,
    cell0_triangle_v2: Vector3,
    cell1_position: Vector3,
    cell1_triangle_v0: Vector3,
    cell1_triangle_v1: Vector3,
    cell1_triangle_v2: Vector3,
]

If there are no errors, the returned array will be empty.

This method is a leftover from when this resource was initially implemented, as an attempt to automate checks when debugging. Errors might not always indicate an unusable SDF, depending on the use case. It might be removed or changed in the future.

AABB get_aabb( )¶

Get the reference bounding box of the baked shape. This may be a bit larger than the original mesh's AABB because of the margin_ratio property.

VoxelBuffer get_voxel_buffer( )¶

Get the VoxelBuffer containing the baked distance field. Results will be stored in the SDF channel.

This buffer should not be modified.

bool is_baked( )¶

Gets whether the resource contains baked SDF data.

bool is_baking( )¶

Gets whether a asynchronous baking operation is pending.

Generated on Jan 26, 2026