Previous
OBJECTs
blob
This object is a blob, that is to say a set of interacting meta-balls.
A blob is the isosurface of a three-dimensional
field, defined by the sum of spherical functions that possess maximum
absolute density at their center and zero density at their border.
For their nature blobs always enclose a solid volume.
- string "threshold", float density
Specify the threshold density value at which the surface is extracted.
- string "blob", vector3 center, float radius, float strength = 1.0
Specify a blob component.
box
This object is an axis aligned box.
- string "position", vector3 c1, vector3 c2
Specify two opposite corners of the box.
boundary
This object allows to define a boundary composed by many
surfaces.
If the boundary is closed it also defines a solid, which may be
used in boolean operations.
- string "surfaces", { object surface } | intarray surfaces
Specify the surfaces that form the boundary.
box
This object is an axis aligned box.
- string "position", vector3 c1, vector3 c2
Specify two opposite corners of the box.
bspline
This object is a bspline patch.
It is a complex type, and its explanation would require an
entire book.
This implementation is similar to the one described in: The
RenderMan Companion, from Addison Wesley.
- string "tolerance", float t
Specify the maximum size of the faces that are used to
approximate the surface.
- string "curvature", float c
Specify the maximum allowed curvature for the final tessellation. If a region has a greater
curvature it is subdivided recursively.
- string "subdivision", int min, int max
Specify the minimum and maximum recursion depth in the surface
subdivision process that produces the final tessellation.
Note that the minimum subdivision is done before rendering and
produces a tessellation that is always stored into memory,
while additive subdivisions are only performed during the
rendering stage if the tessellation was not good enough.
So if the maximum depth is greater than the minimum, the
rendering time may increase significantly:
you should use greater maximum subdivisions only when the physical
memory is not enough to store the final tessellation.
Good subdivision levels are 2 or 3. Since this process is
exponential, 4 is already a very great value.
- string "size", int usize, int vsize
Specify the size of the patch as the number of control points
in the U and V directions.
- string "step", int ustep, int vstep
Specify the U-V steps for the evaluation window.
Predefined values are: BezierStep(), BSplineStep(), CatmullRomStep() and
HermiteStep(), according to the specified basis.
- string "wrap", int uwrap, int vwrap
Specify if the surface is wrapped on the U-V directions.
- string "basis", matrix4 ubasis, matrix4 vbasis
Specify the U-V matrices for the bspline bases.
Predefined values are: BezierBasis(), BSplineBasis(), CatmullRomBasis() and
HermiteBasis().
- string "points", vector3array | vector4array points
Specify the control points as a monodimensional array of
U-rows of points.
The points may be four dimensional, and in this case they are
interpreted as homogenous coordinates, producing a rational surface.
- string "region",
(vector2 c1, vector2 c2) |
(float minu, float minv, float maxu, float maxv)
Specify the visible region of the surface.
The parametric domain is [0,1] x [0,1].
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
- string "trimmer", trimmer trim
Specify the trimmer that is used to trim the visible region of
the surface.
cone
This object is an open cone with the apex pointing in the Z
direction, and the base on XY plane.
- string "radius", float r
Specify the radius of the base of the cone.
- string "height", float h
Specify the height of the cone.
- string "region",
(vector2 u, float maxv, ) |
(float minu, float maxu, float maxv)
Specify the visible region of the surface.
The U parametric direction defines the angle of rotation around
the Z axis.
V isolines define the circles from the base to the apex.
The parametric domain is [0,1] x [0,1].
The region is specified by the minimum and maximum U and by the maximum V.
This means that the cone always starts from its base, even if
it may be truncated before the apex, and only an arc may
be visible.
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
cylinder
This object is an open cylinder parallel to the Z axis, with the
base on the XY plane.
- string "radius", float r
Specify the radius of the base of the cylinder.
- string "height", float h
Specify the height of the cylinder.
- string "region",
(vector2 u) |
(float minu, float maxu)
Specify the visible region of the surface.
The U parametric direction defines the angle of rotation around
the Z axis.
V isolines define the circles from one base to the other.
The parametric domain is [0,1] x [0,1].
The region is specified by the minimum and maximum U, so that
only an arc may be visible.
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
disc
This object is a flat disc on the XY plane.
- string "radius", float r
Specify the radius of the base of the cylinder.
- string "hole", float h
Specify the radius of an optional hole at the center of the disc.
- string "region",
(vector2 u) |
(float minu, float maxu)
Specify the visible region of the surface.
The U parametric direction defines the angle of rotation around
the Z axis.
V isolines define the circles from the center to the border.
The parametric domain is [0,1] x [0,1].
The region is specified by the minimum and maximum U, so that
only an arc may be visible.
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
hfield
This object is a height-field.
In practice it is a square patch, parallel to the X-Y axes, with
varying heights on the Z axis.
It may be used to model geographical landscapes or to represent
real functions of two variables.
- string "size", int usize, int vsize
Specify the number of control points in the U and V directions.
- string "points", floatarray points
Specify the height at each point of the height field.
The values are stored in a monodimensional array made by
concatenating all the U-rows. The size of the array must be usize x vsize.
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
gsurface
This object is an advanced type that allows to handle generic
parametric surfaces, with accurate displacement mapping.
- string "tolerance", float tolerance, float expansionfactor
Specify the maximum size of the faces that are used to
approximate the surface.
expansionfactor has a complex analytical meaning: it is the
necessary expansion factor that is to be applied to the minimal
sphere that contains two arbitrary points of the surface, in order to
contain all the surface segment connecting those points.
For example if two points have a distance of d, and we
know that the sphere containing the segment formed by them
have a diameter of d*(1+e), in order to make the surface render
correctly we have to specify an expansion factor of
e.
In practice this value may not be known a priori, since
we do not always possess the analytical description of the
surface, which may also be the result of very complex
displacement patterns, but we may obtain this value by trials
and by a bit of good sense.
For example we know this value is 0 for
planar surfaces, and making some simple geometric
considerations we may find it is 0 also for spheres.
Then we may notice that an expansion factor equal to or
greater than 1 is needed only for surfaces with infinite area, even
if with finite volume: such surfaces should have fractal peaks
at all scales.
So we have already reduced our research field to the range [0,1[.
Here you can easily search a good value by bisection.
Obviously the smaller this value is, the faster the rendering
times.
- string "curvature", float c
Specify the maximum allowed curvature for the final tessellation. If a region has a greater
curvature it is subdivided recursively.
- string "subdivision", int min, int max
Specify the minimum and maximum recursion depth in the surface
subdivision process that produces the final tessellation.
Note that the minimum subdivision is done before rendering and
produces a tessellation that is always stored into memory,
while additive subdivisions are only performed during the
rendering stage if the tessellation was not good enough.
So if the maximum depth is greater than the minimum, the
rendering time may increase significantly:
you should use greater maximum subdivisions only when the physical
memory is not enough to store the final tessellation.
Good subdivision levels are 2 or 3. Since this process is
exponential, 4 is already a very great value.
- string "sampling", int usamples, int vsamples
Specify the number of U and V samples that are taken for the
initial subdivision.
The greater these values the better the final tessellation.
Note that this value may influence the necessary
expansion factor: if great variations are concentrated at
low frequencies, you may increase the amount of samples and
decrease the expansion factor to obtain the same result in a
faster way.
- string "surface", object surface
Specify the object whose surface is to be rendered.
This object must have a well defined parametric surface, so it
should not be a composite object, like a boundary or a solid
resulting from boolean operations.
nurbs
This object is a nurbs patch.
It is a complex type, and its explanation would require an
entire book.
This implementation is similar to the one described in: The
RenderMan Companion, from Addison Wesley.
- string "tolerance", float t
Specify the maximum size of the faces that are used to
approximate the surface.
- string "curvature", float c
Specify the maximum allowed curvature for the final tessellation. If a region has a greater
curvature it is subdivided recursively.
- string "subdivision", int min, int max
Specify the minimum and maximum recursion depth in the surface
subdivision process that produces the final tessellation.
Note that the minimum subdivision is done before rendering and
produces a tessellation that is always stored into memory,
while additive subdivisions are only performed during the
rendering stage if the tessellation was not good enough.
So if the maximum depth is greater than the minimum, the
rendering time may increase significantly:
you should use greater maximum subdivisions only when the physical
memory is not enough to store the final tessellation.
Good subdivision levels are 2 or 3. Since this process is
exponential, 4 is already a very great value.
- string "size", int usize, int vsize
Specify the size of the patch as the number of control points
in the U and V directions.
- string "degree", int udeg, int vdeg
Specify the U-V degrees of the nurbs surface.
- string "points", vector3array | vector4array points
Specify the control points as a monodimensional array of
U-rows of points.
The points may be four dimensional, and in this case they are
interpreted as homogenous coordinates, producing a rational surface.
- string "knots", floatarray uknots, floatarray vknots
Specify the U-V knot vectors.
The size of the knot vectors should be usize + udegree + 1 and
vsize + vdegree + 1 respectively.
- string "region",
(vector2 c1, vector2 c2) |
(float minu, float minv, float maxu, float maxv)
Specify the visible region of the surface.
The parametric domain is directly determined by the knot vectors.
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
- string "trimmer", trimmer trim
Specify the trimmer that is used to trim the visible region of
the surface.
patch
This object is a bilinear patch.
A bilinear patch is the surface formed connecting two lines by
linear interpolation. The edges of this surface are always
straight lines, but the interior may be non planar.
In particular if the two original lines are not coplanar
the resulting patch is a piece of hyperboloid.
- string "points", vector3 p1, vector3 p2, vector3 p3, vector3 p4
Specify the four control points.
You can imagine the patch to be the surface that connects the
two edges p1-p2 and p3-p4, or equivalently p1-p3 and p2-p4.
Note that the control points are not connected sequentially:
the resulting polygon is p1-p2-p4-p3.
- string "normals", vector3 n1, vector3 n2, vector3 n3, vector3 n4
Specify the normals at the four control points.
If you do not set them the real geometric normals are used.
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
solid
This object is a solid resulting from a boolean operation between
two different objects.
- string "type", string operation
Specify the type of boolean operation.
Valid types are:
- "union" : joins the two objects
- "difference" : subtracts the second object from the first
- "intersection" : intersects the two objects
- string "solids", object o1, object o2
Specify the two objects involved in the boolean operation.
These two objects must have a well defined interior, and so
their surface must be closed.
- string "closure", int switch
Specify if the resulting solid is closed (switch = 1) or open
(switch = 0).
This attribute affects only intersections and differences: in
these cases if it is set to 0 the surface of the second object
will not be visible, leaving an open side.
sphere
This object is a sphere centered in the local origin.
- string "radius", float r
Specify the radius of the sphere.
- string "region",
(vector2 minuv, vector2 maxuv, ) |
(float minu, float minv, float maxu, float maxv)
Specify the visible region of the surface.
The U parametric direction defines the angle of rotation around
the Z axis.
V isolines define the circles between the south and north poles.
The parametric domain is [0,1] x [0,1].
- string "texture",
(vector2 c1, vector2 c2, vector2 c3, vector2 c4) |
(float u1, float v1, float u2, float v2, float u3, float v3, float u4, float v4)
Specify the texture coordinates at the four corners of the surface.
surface-engine
This object is an advanced type that allows to handle very large sets of generic
parametric surfaces, with accurate displacement mapping.
It is very useful when rendering complex models defined by a
great number of triangles that after displacement mapping assume
curved shapes.
The surface-engine is highly optimized to handle quantities of
geometry that exceed the physical memory.
- string "tolerance", float low-tolerance, float hi-tolerance, float expansionfactor
Specify the maximum size of the faces that are used to
approximate the surface.
The surface-engine works in two stages: in the first phase it
splits all the geometry in faces smaller than hi-tolerance, in
order to obtain a global but rough approximation of the entire
surface, while in the final phase, that is performed at
run-time during ray-tracing, it refines only the faces that are going
to be hit by the current ray, so that their size is less than
low-tolerance.
expansionfactor has a complex analytical meaning: it is the
necessary expansion factor that is to be applied to the minimal
sphere that contains two arbitrary points of the surface, in order to
contain all the surface segment connecting those points.
For example if two points have a distance of d, and we
know that the sphere containing the segment formed by them
have a diameter of d*(1+e), in order to make the surface render
correctly we have to specify an expansion factor of
e.
In practice this value may not be known a priori, since
we do not always possess the analytical description of the
surface, which may also be the result of very complex
displacement patterns, but we may obtain this value by trials
and by a bit of good sense.
For example we know this value is 0 for
planar surfaces, and making some simple geometric
considerations we may find it is 0 also for spheres.
Then we may notice that an expansion factor equal to or
greater than 1 is needed only for surfaces with infinite area, even
if with finite volume: such surfaces should have fractal peaks
at all scales.
So we have already reduced our research field to the range [0,1[.
Here you can easily search a good value by bisection.
Obviously the smaller this value is, the faster the rendering
times.
- string "curvature", float c
Specify the maximum allowed curvature for the final tessellation. If a region has a greater
curvature it is subdivided recursively.
- string "caching", int memory
Specify the memory occupancy of the geometry cache in Kb.
This is the maximum quantity of memory used to handle the
surface resulting from the final tessellation, no matter how
small the low-tolerance is.
Obviously, the smaller is the cache the slower the rendering.
The default value is 8192.
- string "surfaces", { object surface } | objectarray surfaces
Specify the set of objects whose surface is to be rendered.
These objects must have a well defined parametric surface, so they
should not be composite objects, like boundaries or solids
resulting from boolean operations.
triangle
This object is a triangle.
- string "points", vector3 p1, vector3 p2, vector3 p3
Specify the three corners of the triangle.
- string "normals", vector3 n1, vector3 n2, vector3 n3
Specify the normals at the three corners of the triangle.
If you do not set them the real geometric normal is used.
- string "texture",
(vector2 c1, vector2 c2, vector2 c3) |
(float u1, float v1, float u2, float v2, float u3, float v3)
Specify the texture coordinates at the three corners of the surface.