Shapes

This section presents an overview of the shape plugins that are released along with the renderer.

In Mitsuba 3, shapes define surfaces that mark transitions between different types of materials. For instance, a shape could describe a boundary between air and a solid object, such as a piece of rock. Alternatively, a shape can mark the beginning of a region of space that isn’t solid at all, but rather contains a participating medium, such as smoke or steam. Finally, a shape can be used to create an object that emits light on its own.

Shapes are usually declared along with a BSDF characterizing the material’s response to light (see the respective section for more detail).

XMLPython

<scene version="3.0.0">
    <!-- .. scene contents .. -->

    <shape type=".. shape type ..">
        .. shape parameters ..

        <bsdf type=".. BSDF type ..">
            .. bsdf parameters ..
        </bsdf>

        <!-- Alternatively: reference a named BSDF that
            has been declared previously

            <ref id="my_bsdf"/>
        -->
    </shape>
</scene>

Mesh parameters

Mitsuba provides several plugins that represent their geometry as a triangle mesh: obj, ply, and serialized load meshes from the file format of the same name, and cube provides a built-in box primitive. All of them are instances of the same underlying mesh class and therefore expose an identical set of scene parameters through mi.traverse().

The parameters are row-major tensors, with F faces, V vertices, P surface points, and N normal groups:

Parameter	Type	Description	Flags
faces	TensorXu (F, 3)	Vertex indices of each triangle, in [0, V)	P, D
bsdf_index	UInt32 (F,)	Per-face BSDF index. An empty list indicates that all faces use BSDF entry 0.	P
position_index	UInt32 (V,)	Surface point of each vertex, in [0, P). An empty list encodes the identity and indicates that P == V.	P, D
positions	TensorXf (P, 3)	Surface point positions in world space	P, ∂, D
normal_index	UInt32 (V,)	Normal group of each vertex, in [0, N). An empty list encodes the identity and indicates that N == V.	P
normals	TensorXf (N, 3)	Shading normals in world space, only present on meshes with vertex normals	P, ∂, D
texcoords	TensorXf (V, 2)	Per-vertex texture coordinates, only present on meshes with a UV parameterization	P, ∂
(Mesh attribute)	TensorXf (V, d) or (F, d)	Custom per-vertex or per-face attribute with d channels	P, ∂

Mitsuba Mesh class can choose to store attributes (positions, normals, UVs) at different granularities. This makes it possible to represent shapes that are geometrically continuous while having discontinuous normals or UVs. For example, it is relatively common for a mesh to have a crease edge where normals jump, or separate UV patches covering the geoemtry.

The naive way to represent parameter disconinuities involves splitting vertices so that the faces on either side get their own copy, but this also cuts the geometry apart. This causes normal creases, discontinuities in a differentiable renderer, and tearing under optimization.

Mitsuba uses the position_index and normal_index maps to map vertex indices to potentially coarser position and normal indices, so that copies split at a seam still reference the same underlying position or normal. This sharing removes the drawbacks of naive splitting mentioned above.

Everything else (texture coordinates, tangents, and mesh attributes) is indexed by vertex. Reading the texture coordinate of corner c of face f is therefore a direct lookup,

vertex_idx = faces[f][c]
texcoord   = texcoords[vertex_idx]

while positions and normals take one further step through their map:

vertex_idx   = faces[f][c]
position_idx = position_index[vertex_idx] if len(position_index) > 0 else vertex_idx
position     = positions[position_idx]

All parameters are writable and can may also change in shape (e.g., when remeshing to a different mesh resolution). Following an update, Mitsuba automatically keeps dependent state in sync, e.g., by regenerating shading normals when the geometry changes but no new normals were provided by the user.

The following subsections discuss the available shape types in greater detail.

Wavefront OBJ mesh loader (obj)

Parameter	Type	Description	Flags
filename	string	Filename of the OBJ file that should be loaded
face_normals	boolean	When set to true, any existing or computed vertex normals are discarded and face normals will instead be used during rendering. This gives the rendered object a faceted appearance. (Default: false)
flip_tex_coords	boolean	Treat the vertical component of the texture as inverted? Most OBJ files use this convention. (Default: true)
flip_normals	boolean	Is the mesh inverted, i.e. should the normal vectors be flipped? (Default:false, i.e. the normals point outside)
to_world	transform	Specifies an optional linear object-to-world transformation. (Default: none, i.e. object space = world space)

In addition, this plugin exposes the standard mesh state parameters documented in Mesh parameters.

This plugin implements a simple loader for Wavefront OBJ files. It handles meshes containing triangles and quadrilaterals, and it also imports vertex normals and texture coordinates.

Loading an ordinary OBJ file is as simple as writing:

XMLPython

<shape type="obj">
    <string name="filename" value="my_shape.obj"/>
</shape>

Note

Importing geometry via OBJ files should only be used as an absolutely last resort. Due to inherent limitations of this format, the files tend to be unreasonably large, and parsing them requires significant amounts of memory and processing power. What’s worse is that the internally stored data is often truncated, causing a loss of precision. If possible, use the ply or serialized plugins instead.

PLY (Stanford Triangle Format) mesh loader (ply)

Parameter	Type	Description	Flags
filename	string	Filename of the PLY file that should be loaded
face_normals	boolean	When set to true, any existing or computed vertex normals are discarded and face normals will instead be used during rendering. This gives the rendered object a faceted appearance. (Default: false)
flip_tex_coords	boolean	Treat the vertical component of the texture as inverted? (Default: false)
flip_normals	boolean	Is the mesh inverted, i.e. should the normal vectors be flipped? (Default:false, i.e. the normals point outside)
to_world	transform	Specifies an optional linear object-to-world transformation. (Default: none, i.e. object space = world space)

In addition, this plugin exposes the standard mesh state parameters documented in Mesh parameters.

The Stanford bunny loaded with face_normals=false.¶

The Stanford bunny loaded with face_normals=true. Note the faceted appearance.¶

This plugin implements a fast loader for the Stanford PLY format (both the ASCII and binary format, which is preferred for performance reasons). The current plugin implementation supports triangle meshes with optional UV coordinates, vertex normals and other custom vertex or face attributes.

Consecutive attributes with names sharing a common prefix and using one of the following schemes:

{prefix}_{x|y|z|w}, {prefix}_{r|g|b|a}, {prefix}_{0|1|2|3}, {prefix}_{1|2|3|4}

will be group together under a single multidimensional attribute named {vertex|face}_{prefix}.

RGB color attributes can also be defined without a prefix, following the naming scheme {r|g|b|a} or {red|green|blue|alpha}. Those attributes will be group together under a single multidimensional attribute named {vertex|face}_color.

XMLPython

<shape type="ply">
    <string name="filename" value="my_shape.ply"/>
    <boolean name="flip_normals" value="true"/>
</shape>

Note

Values stored in a RBG color attribute will automatically be converted into spectral model coefficients when using a spectral variant of the renderer.

Serialized mesh loader (serialized)

Parameter	Type	Description	Flags
filename	string	Filename of the serialized file that should be loaded
shape_index	integer	A .serialized file may contain several separate meshes. This parameter specifies which one should be loaded. (Default: 0, i.e. the first one)
face_normals	boolean	When set to true, any existing or computed vertex normals are discarded and emph{face normals} will instead be used during rendering. This gives the rendered object a faceted appearance. (Default: false)
flip_normals	boolean	Is the mesh inverted, i.e. should the normal vectors be flipped? (Default:false, i.e. the normals point outside)
to_world	transform	Specifies an optional linear object-to-world transformation. (Default: none, i.e. object space = world space)

In addition, this plugin exposes the standard mesh state parameters documented in Mesh parameters.

The serialized mesh format represents the most space and time-efficient way of getting geometry information into Mitsuba 3. It stores indexed triangle meshes in a lossless gzip-based encoding that (after decompression) nicely matches up with the internally used data structures. Loading such files is considerably faster than the ply plugin and orders of magnitude faster than the obj plugin.

Format description

The serialized file format uses the little endian encoding, hence all fields below should be interpreted accordingly. The contents of a version 5 file are structured as follows:

Type	Content
uint16	File format identifier: 0x041C
uint16	File version identifier. Currently set to 0x0005
\(\rightarrow\)	From this point on, the stream is compressed by the DEFLATE algorithm.
\(\rightarrow\)	The used encoding is that of the zlib library.
uint32	An 32-bit integer whose bits can be used to specify the following flags: 0x0007: The low bits store the vertex record layout: 0x1 denotes stored shading normals, 0x2 shading tangents, and 0x4 texture coordinates. Tangents occupy no lanes of their own: the frame lanes then hold the whole encoded shading frame instead of just the normal 0x0010: Use face normals instead of smoothly interpolated vertex normals. Equivalent to specifying face_normals=true to the plugin. 0x0020: The stored shading normals were supplied by the user, rather than generated from the positions (in which case a position edit through the parameter interface recomputes them) 0x1000: The subsequent content is represented in single precision (always set; version 5 files are single precision)
string	The name of the shape: a uint32 length followed by that many utf-8 bytes.
uint64	Number of vertices V in the mesh
uint64	Number of triangles F in the mesh
uint64	Number of distinct surface points P, or 0 when the vertex-to-surface-point map is the identity and not stored
uint64	Number of normal groups N, or 0 when the vertex-to-normal-group map is the identity and not stored
array	8 V single precision floats: the packed vertex records (position in lanes 0-2, the shading normal or, with stored tangents, the encoded shading frame in lanes 3-5, texture coordinates in lanes 6-7; unused lanes are zero)
array	4 F uint32 face records: three vertex indices and the per-face BSDF index
array	V uint32 vertex-to-surface-point indices in [0, P). Omitted when P is 0.
array	V uint32 vertex-to-normal-group indices in [0, N). Omitted when N is 0.
uint32	Number of custom mesh attributes
attribute	Per attribute: a length-prefixed name whose vertex_ or face_ prefix selects the domain, a uint8 flag byte (bit 0: the values are sRGB-to-spectrum upsampling coefficients written by a spectral variant rather than raw values), a uint32 channel count dim in [1, 4], and V dim (or F dim) single precision floats of attribute data

Version 3 and 4 files instead store a single-indexed triangle mesh: the flag word (with 0x0001 denoting normals, 0x0002 texture coordinates, 0x0008 vertex colors and 0x2000 double precision data), the null-terminated shape name (version 4 only), the vertex and triangle counts V and F, and arrays of per-vertex positions, normals, texture coordinates and colors, followed by 3 F uint32 face indices.

Multiple shapes

It is possible to store multiple meshes in a single .serialized file. This is done by simply concatenating their data streams, where every one is structured according to the above description. Hence, after each mesh, the stream briefly reverts back to an uncompressed format, followed by an uncompressed header, and so on. This is necessary for efficient read access to arbitrary sub-meshes.

End-of-file dictionary

In addition to the previous table, a .serialized file also concludes with a brief summary at the end of the file, which specifies the starting position of each sub-mesh:

Type	Content
uint64	File offset of the first mesh (in bytes)—this is always zero.
uint64	File offset of the second mesh
\(\cdots\)	\(\cdots\)
uint64	File offset of the last sub-shape
uint32	Total number of meshes in the .serialized file

XMLPython

<shape type="serialized">
    <string name="filename" value="shape.serialized"/>
    <bsdf type='diffuse'/>
</shape>

Cube (cube)

Parameter	Type	Description	Flags
flip_normals	boolean	Is the cube inverted, i.e. should the normal vectors be flipped? (Default:false, i.e. the normals point outside)
to_world	transform	Specifies an optional linear object-to-world transformation. (Default: none (i.e. object space = world space))

In addition, this plugin exposes the standard mesh state parameters documented in Mesh parameters.

This shape plugin describes a cube intersection primitive, based on the triangle mesh class. By default, it creates a cube between the world-space positions (−1, −1, −1) and (1, 1, 1). However, an arbitrary linear transformation may be specified to translate, rotate, scale or skew it as desired. The parameterization of this shape maps every face onto the rectangle \([0, 1]^2\) in uv space.

XMLPython

<shape type="cube">
    <transform name="to_world">
        <scale x="2" y="10" z="1"/>
    </transform>
</shape>

Sphere (sphere)

Parameter	Type	Description	Flags
center	point	Center of the sphere (Default: (0, 0, 0))
radius	float	Radius of the sphere (Default: 1)
flip_normals	boolean	Is the sphere inverted, i.e. should the normal vectors be flipped? (Default:false, i.e. the normals point outside)
to_world	transform	Specifies an optional linear object-to-world transformation. Note that non-uniform scales and shears are not permitted! (Default: none, i.e. object space = world space)	P, ∂, D
silhouette_sampling_weight	float	Weight associated with this shape when sampling silhoeuttes in the scene. (Default: 1)	P

Basic example¶

A textured sphere with the default parameterization¶

This shape plugin describes a simple sphere intersection primitive. It should always be preferred over sphere approximations modeled using triangles.

A sphere can either be configured using a linear to_world transformation or the center and radius parameters (or both). The two declarations below are equivalent.

XMLPython

<shape type="sphere">
    <transform name="to_world">
        <translate x="1" y="0" z="0"/>
        <scale value="2"/>
    </transform>
    <bsdf type="diffuse"/>
</shape>

<shape type="sphere">
    <point name="center" x="1" y="0" z="0"/>
    <float name="radius" value="2"/>
    <bsdf type="diffuse"/>
</shape>

When a sphere shape is turned into an area light source, Mitsuba 3 switches to an efficient sampling strategy by Fred Akalin that has particularly low variance. This makes it a good default choice for lighting new scenes.

Spherical area light modeled using triangles¶

Spherical area light modeled using the sphere plugin¶

Rectangle (rectangle)

Parameter	Type	Description	Flags
flip_normals	boolean	Is the rectangle inverted, i.e. should the normal vectors be flipped? (Default: false)
to_world	transform	Specifies a linear object-to-world transformation. (Default: none (i.e. object space = world space))	P, ∂, D
silhouette_sampling_weight	float	Weight associated with this shape when sampling silhoeuttes in the scene. (Default: 1)	P

Basic example¶

A textured rectangle with the default parameterization¶

This shape plugin describes a simple rectangular shape primitive. It is mainly provided as a convenience for those cases when creating and loading an external mesh with two triangles is simply too tedious, e.g. when an area light source or a simple ground plane are needed. By default, the rectangle covers the XY-range \([-1,1]\times[-1,1]\) and has a surface normal that points into the positive Z-direction. To change the rectangle scale, rotation, or translation, use the to_world parameter.

The following XML snippet showcases a simple example of a textured rectangle:

XMLPython

<shape type="rectangle">
    <bsdf type="diffuse">
        <texture name="reflectance" type="checkerboard">
            <transform name="to_uv">
                <scale x="5" y="5" />
            </transform>
        </texture>
    </bsdf>
</shape>

Disk (disk)

Parameter	Type	Description	Flags
flip_normals	boolean	Is the disk inverted, i.e. should the normal vectors be flipped? (Default: false)
to_world	transform	Specifies a linear object-to-world transformation. Note that non-uniform scales are not permitted! (Default: none, i.e. object space = world space)	P, ∂, D
silhouette_sampling_weight	float	Weight associated with this shape when sampling silhoeuttes in the scene. (Default: 1)	P

Basic example¶

A textured disk with the default parameterization¶

This shape plugin describes a simple disk intersection primitive. It is usually preferable over discrete approximations made from triangles.

By default, the disk has unit radius and is located at the origin. Its surface normal points into the positive Z-direction. To change the disk scale, rotation, or translation, use the to_world parameter.

The following XML snippet instantiates an example of a textured disk shape:

XMLPython

<shape type="disk">
    <bsdf type="diffuse">
        <texture name="reflectance" type="checkerboard">
            <transform name="to_uv">
                <scale x="2" y="10" />
            </transform>
        </texture>
    </bsdf>
</shape>

Cylinder (cylinder)

Parameter	Type	Description	Flags
p0	point	Object-space starting point of the cylinder’s centerline. (Default: (0, 0, 0))
p1	point	Object-space endpoint of the cylinder’s centerline (Default: (0, 0, 1))
radius	float	Radius of the cylinder in object-space units (Default: 1)
flip_normals	boolean	Is the cylinder inverted, i.e. should the normal vectors be flipped? (Default: false, i.e. the normals point outside)
to_world	transform	Specifies an optional linear object-to-world transformation. Note that non-uniform scales are not permitted! (Default: none, i.e. object space = world space)	P, ∂, D
silhouette_sampling_weight	float	Weight associated with this shape when sampling silhoeuttes in the scene. (Default: 1)	P

Cylinder with the default one-sided shading¶

Cylinder with two-sided shading¶

This shape plugin describes a simple cylinder intersection primitive. It should always be preferred over approximations modeled using triangles. Note that the cylinder does not have endcaps – also, its normals point outward, which means that the inside will be treated as fully absorbing by most material models. If this is not desirable, consider using the twosided plugin.

A simple example for instantiating a cylinder, whose interior is visible:

XMLPython

<shape type="cylinder">
    <float name="radius" value="0.3"/>
    <bsdf type="twosided">
        <bsdf type="diffuse"/>
    </bsdf>
</shape>

B-spline curve (bsplinecurve)

Parameter	Type	Description	Flags
filename	string	Filename of the curves to be loaded
to_world	transform	Specifies a linear object-to-world transformation. Note that the control points’ raddii are invariant to this transformation!
silhouette_sampling_weight	float	Weight associated with this shape when sampling silhoeuttes in the scene. (Default: 1)	P
State parameters
control_point_count	integer	Total number of control points	P
segment_indices	uint32[]	Starting indices of a B-Spline segment	P
control_points	float[]	Flattened control points buffer pre-multiplied by the object-to-world transformation. Each control point in the buffer is structured as follows: position_x, position_y, position_z, radius	P, ∂, D

Basic example¶

A textured B-spline curve with the default parameterization¶

This shape plugin describes multiple cubic B-spline curves. They are hollow cylindrical tubes which can have varying radii along their length and are open-ended: they do not have endcaps. They can be made watertight by setting the radii of the extremities to 0. This shape should always be preferred over curve approximations modeled using triangles.

Although it is possible to define multiple curves as multiple separate objects, this plugin was intended to be used as an aggregate of curves. Of course, if the individual curves need different materials or other individual characteristics they need to be defined in separate objects.

The file from which curves are loaded defines a single control point per line using four real numbers. The first three encode the position and the last one is the radius of the control point. At least four control points need to be specified for a single curve. Empty lines between control points are used to indicate the beginning of a new curve. Here is an example of two curves, the first with 4 control points and static radii and the second with 6 control points and increasing radii:

-1.0 0.1 0.1 0.5
-0.3 1.2 1.0 0.5
 0.3 0.3 1.1 0.5
 1.0 1.4 1.2 0.5

-1.0 5.0 2.2 1
-2.3 4.0 2.3 2
 3.3 3.0 2.2 3
 4.0 2.0 2.3 4
 4.0 1.0 2.2 5
 4.0 0.0 2.3 6

XMLPython

<shape type="bsplinecurve">
    <transform name="to_world">
        <scale value="2"/>
        <translate x="1" y="0" z="0"/>
    </transform>
    <string name="filename" type="curves.txt"/>
</shape>

Note

The backfaces of curves are always culled. It is therefore impossible to intersect the curve with a ray that’s origin is inside of the curve.

Linear curve (linearcurve)

Parameter	Type	Description	Flags
filename	string	Filename of the curves to be loaded
to_world	transform	Specifies a linear object-to-world transformation. Note that the control points’ raddii are invariant to this transformation!
State parameters
control_point_count	integer	Total number of control points	P
segment_indices	uint32[]	Starting indices of a linear segment	P
control_points	float[]	Flattened control points buffer pre-multiplied by the object-to-world transformation. Each control point in the buffer is structured as follows: position_x, position_y, position_z, radius	P

Basic example¶

A textured linear curve with the default parameterization¶

This shape plugin describes multiple linear curves. They are hollow cylindrical tubes which can have varying radii along their length. The linear segments are connected by a smooth spherical joint, and they are also terminated by a spherical endcap. This shape should always be preferred over curve approximations modeled using triangles.

Although it is possible to define multiple curves as multiple separate objects, this plugin was intended to be used as an aggregate of curves. Of course, if the individual curves need different materials or other individual characteristics they need to be defined in separate objects.

The file from which curves are loaded defines a single control point per line using four real numbers. The first three encode the position and the last one is the radius of the control point. At least two control points need to be specified for a single curve. Empty lines between control points are used to indicate the beginning of a new curve. Here is an example of two curves, the first with 2 control points and static radii and the second with 4 control points and increasing radii:

-1.0 0.1 0.1 0.5
 1.0 1.4 1.2 0.5

-1.0 5.0 2.2 1
-2.3 4.0 2.3 2
 4.0 1.0 2.2 5
 4.0 0.0 2.3 6

XMLPython

<shape type="linearcurve">
    <transform name="to_world">
        <translate x="1" y="0" z="0"/>
        <scale value="2"/>
    </transform>
    <string name="filename" type="curves.txt"/>
</shape>

Note

The backfaces of curves are always culled. It is therefore impossible to intersect the curve with a ray that’s origin is inside of the curve.

SDF Grid (sdfgrid)

Parameter	Type	Description	Flags
filename	string	Filename of the SDF grid data to be loaded. The expected file format aligns with a single-channel grid-based volume data source. If no filename is provided, the shape is initialised as an empty 2x2x2 grid.
grid	tensor	Tensor array containing the grid data. This parameter can only be specified when building this plugin at runtime from Python or C++ and cannot be specified in the XML scene description.	P, ∂, D
normals	string	Specifies the method for computing shading normals. The options are analytic or smooth. (Default: smooth)
to_world	transform	Specifies a linear object-to-world transformation. (Default: none (i.e. object space = world space))	P, ∂, D

SDF grid with smooth shading normals¶

SDF grid with analytic shading normals¶

This shape plugin describes a signed distance function (SDF) grid shape primitive — that is, an SDF sampled onto a three-dimensional grid. The grid object-space is mapped over the range \([0,1]^3\).

A smooth method for computing normals [SEAM22] is selected as the default approach to ensure continuity across grid cells.

Warning

Compared with the other available shape plugins, the SDF grid has a few important limitations. Namely:

• It does not emit UV coordinates for texturing.

• It cannot be used as an area emitter.

Note

When differentiating this shape, it does not leverage the work presented in [VSJ22]. However, a Mitsuba 3-based implementation of that technique is available on its project’s page.

XMLPython

<shape type="sdfgrid">
    <string name="filename" value="data.sdf"/>
    <bsdf type="diffuse"/>
</shape>

Shape group (shapegroup)

Parameter	Type	Description	Flags
(Nested plugin)	shape	One or more shapes that should be made available for geometry instancing

This plugin implements a container for shapes that should be made available for geometry instancing. Any shapes placed in a shapegroup will not be visible on their own—instead, the renderer will precompute ray intersection acceleration data structures so that they can efficiently be referenced many times using the Instance (instance) plugin. This is useful for rendering things like forests, where only a few distinct types of trees have to be kept in memory. An example is given below:

XMLPython

<!-- Declare a named shape group containing two objects -->
<shape type="shapegroup" id="my_shape_group">
    <shape type="ply">
        <string name="filename" value="data.ply"/>
        <bsdf type="roughconductor"/>
    </shape>
    <shape type="sphere">
        <transform name="to_world">
            <translate y="20"/>
            <scale value="5"/>
        </transform>
        <bsdf type="diffuse"/>
    </shape>
</shape>

<!-- Instantiate the shape group without any kind of transformation -->
<shape type="instance">
    <ref id="my_shape_group"/>
</shape>

<!-- Create instance of the shape group, but rotated, scaled, and translated -->
<shape type="instance">
    <ref id="my_shape_group"/>
    <transform name="to_world">
        <translate z="10"/>
        <scale value="1.5"/>
        <rotate x="1" angle="45"/>
    </transform>
</shape>

Instance (instance)

Parameter	Type	Description	Flags
(Nested plugin)	shapegroup	A reference to a shape group that should be instantiated.
to_world	transform	Specifies a linear object-to-world transformation. (Default: none (i.e. object space = world space))	P, ∂, D

This plugin implements a geometry instance used to efficiently replicate geometry many times. For details on how to create instances, refer to the Shape group (shapegroup) plugin.

The Stanford bunny loaded a single time and instantiated 1365 times (equivalent to 100 million triangles)

Warning

• Note that it is not possible to assign a different material to each instance. The material assignment specified within the shape group is the one that matters.

• Shape groups cannot be used to replicate shapes with attached emitters, sensors, or subsurface scattering models.

Ellipsoids (ellipsoids)

Parameter	Type	Description	Flags
filename	string	Specifies the PLY file containing the ellipsoid centers, scales, and quaternions. This parameter cannot be used if data or centers are provided.
data	tensor	A tensor of shape (N, 10) or (N * 10) that defines the ellipsoid centers, scales, and quaternions. This parameter cannot be used if filename or centers are provided.
centers	tensor	A tensor of shape (N, 3) specifying the ellipsoid centers. This parameter cannot be used if filename or data are provided.
scales	tensor	A tensor of shape (N, 3) specifying the ellipsoid scales. This parameter cannot be used if filename or data are provided.
quaternions	tensor	A tensor of shape (N, 3) specifying the ellipsoid quaternions. This parameter cannot be used if filename or data are provided.
scale_factor	float	A scaling factor applied to all ellipsoids when loading from a PLY file. (Default: 1.0)
extent	float	Specifies the extent of the ellipsoid. This effectively acts as an extra scaling factor on the ellipsoid, without having to alter the scale parameters. (Default: 3.0)	R
extent_adaptive_clamping	float	If True, use adaptive extent values based on the opacities attribute of the volumetric primitives. (Default: False)	R
to_world	transform	Specifies an optional linear object-to-world transformation to apply to all ellipsoids.	P, ∂, D
(Nested plugin)	tensor	Specifies arbitrary ellipsoids attribute as a tensor of shape (N, D) with D the dimensionality of the attribute. For instance this can be used to define an opacity value for each ellipsoids, or a set of spherical harmonic coefficients as used in the volprim_rf_basic integrator.

This shape plugin defines a point cloud of anisotropic ellipsoid primitives using specified centers, scales, and quaternions. It employs a closed-form ray-intersection formula with backface culling. Although it is slower than the ellipsoidsmesh shape plugin, which uses tessellated ellipsoids for ray-triangle intersection hardware acceleration, it offers greater flexibility in computing intersections.

This shape also exposes an extent parameter, it acts as an extra scaling factor for the ellipsoids’ scales. Typically, this is used to define the support of a kernel function defined within the ellipsoid. For example, the scale parmaters of the ellipsoid will define the variances of a gaussian and the extent will multiple those value to define the effictive radius of the ellipsoid. When extent_adaptive_clamping is enabled, the extent is additionally multiplied by an opacity-dependent factor:\(\sqrt{2 * \log(opacity / 0.01)} / 3\)

It is designed for use with volumetric primitive integrators, as detailed in [CSB+25].

XMLPython

<shape type="ellipsoids">
    <string name="filename" value="my_primitives.ply"/>
</shape>

Mesh ellipsoids (ellipsoidsmesh)

Parameter	Type	Description	Flags
filename	string	Specifies the PLY file containing the ellipsoid centers, scales, and quaternions. This parameter cannot be used if data or centers are provided.
data	tensor	A tensor of shape (N, 10) or (N * 10) that defines the ellipsoid centers, scales, and quaternions. This parameter cannot be used if filename or centers are provided.
centers	tensor	A tensor of shape (N, 3) specifying the ellipsoid centers. This parameter cannot be used if filename or data are provided.
scales	tensor	A tensor of shape (N, 3) specifying the ellipsoid scales. This parameter cannot be used if filename or data are provided.
quaternions	tensor	A tensor of shape (N, 3) specifying the ellipsoid quaternions. This parameter cannot be used if filename or data are provided.
scale_factor	float	A scaling factor applied to all ellipsoids when loading from a PLY file. (Default: 1.0)
extent	float	Specifies the extent of the ellipsoid. This effectively acts as an extra scaling factor on the ellipsoid, without having to alter the scale parameters. (Default: 3.0)	R
extent_adaptive_clamping	float	If True, use adaptive extent values based on the opacities attribute of the volumetric primitives. (Default: False)	R
shell	string or |mesh|	Specifies the shell type. Could be one of box, ico_sphere, or uv_sphere, as well as a custom child mesh object. (Default: ico_sphere)
to_world	transform	Specifies an optional linear object-to-world transformation to apply to all ellipsoids.	P, ∂, D
(Nested plugin)	tensor	Specifies arbitrary ellipsoids attribute as a tensor of shape (N, D) with D the dimensionality of the attribute. For instance this can be used to define an opacity value for each ellipsoids, or a set of spherical harmonic coefficients as used in the volprim_rf_basic integrator.

This shape plugin defines a point cloud of anisotropic ellipsoid primitives given centers, scales, and quaternions, using a mesh-based representation with backface culling. This plugin is designed to leverage hardware acceleration for ray-triangle intersections, providing a performance advantage over analytical ellipsoid representations.

This shape also exposes an extent parameter, it acts as an extra scaling factor for the ellipsoids’ scales. Typically, this is used to define the support of a kernel function defined within the ellipsoid. For example, the scale parmaters of the ellipsoid will define the variances of a gaussian and the extent will multiple those value to define the effictive radius of the ellipsoid. When extent_adaptive_clamping is enabled, the extent is additionally multiplied by an opacity-dependent factor:\(\sqrt{2 * \log(opacity / 0.01)} / 3\)

This shape is designed for use with volumetric primitive integrators, as detailed in [CSB+25].

XMLPython

<shape type="ellipsoidsmesh">
    <string name="filename" value="my_primitives.ply"/>
</shape>