Geometry Types
==============
.. contents:: Table of Contents
:depth: 2
:local:
.. _polymesh:
``polymesh``
~~~~~~~~~~~~
Polygonal mesh geometry. A polygonal mesh is formed of points, a vertex list
(defining vertices) and start index list (defining faces). Additional
information, such as normals and arbitrary data, can also be defined.
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`float[3n]`
* :kat:attr:`geometry.point.N`
* List of per-point normals.
- * :kat:type:`float[3n]`
* :kat:attr:`geometry.point.P`
* List of points. The geometry points are unique floating point positions
in object space coordinates (x, y, z). Each point is only stored once
but it may be indexed many times by a particular vertex.
- * :kat:type:`int[]`
* :kat:attr:`geometry.poly.startIndex`
* A list of indices defining the faces of a mesh. For example,
consider a cube. A cube has a :kat:attr:`startIndex` list size equal to
the number of faces in the mesh plus one. This is because we must store
the index of the first point on the first face as well as the end point
of all the faces (including the first). So, for example, the beginning
of a cube's :kat:attr:`startIndex` list may look like:
* 0 - 0
* 1 - 4
* 2 - 8
The indices for each polygon N are from ``startIndex(N)`` to
``startIndex(N+1)-1``. The value at index 0 of the list tells us the
first face should start at index 0 in the ``vertexList``, the second
value in the list tells us the first face ends at index 3 (``n-1``).
- * :kat:type:`int[]`
* :kat:attr:`geometry.poly.vertexList`
* Describes the vertex data of a mesh. There is a vertex at each edge
intersection. The value of the :kat:attr:`vertexList` is used as an
index into the :kat:attr:`geometry.point.P` list, which stores the
actual object coordinates of each unique point. Many indices in a
:kat:attr:`vertexList` can index the same point in the
:kat:attr:`geometry.point.P` list. This saves space as a vertex is
described as a simple integer rather then the three floating point
values required to describe a 3D geometry point (x, y, z).
- * :kat:type:`float[3n]`
* :kat:attr:`geometry.vertex.N`
* List of per-face vertex normals.
- * :kat:type:`float[2n]`
* :kat:attr:`geometry.vertex.UV`
* List of texture coordinates (per vertex, non face-varying)
``subdmesh``
~~~~~~~~~~~~
Sub-division surfaces geometry. Sub-division surfaces (Subds) are similarly
structured to polygonal meshes.
.. note::
This section is under construction.
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`int`
* :kat:attr:`geometry.facevaryinginterpolateboundary`
* An integer indicating how face-varying data is interpolated.
- * :kat:type:`int`
* :kat:attr:`geometry.facevaryingpropagatecorners`
*
- * :kat:type:`int`
* :kat:attr:`geometry.interpolateBoundary`
* An integer indicating the boundary interpolation rule.
- * :kat:type:`int`
* :kat:attr:`geometry.triangleSubdivisionRule`
* An integer indicating a rule added to the Catmull-Clark scheme that modifies the behavior
at triangular faces.
- * :kat:type:`int[]`
* :kat:attr:`geometry.holePolyIndices``
* A list of the indices of faces that should be treated as hole.
- * :kat:type:`int[]`
* :kat:attr:`geometry.creaseIndices`
* A list of vertex indices grouped by successive edges to be creased. The number of indices of each group must be specified in `creaseLengths`.
.. note::
Here is an example to define creases with per-crease sharpness on two faces that made of ``vertexList = [p0, p1, p2, p3, p4, p5]``:
- ``creaseIndices = [0, 1, 2, 0, 3, 4]`` - ``[0, 1, 2, 0]`` is a crease made of three edges in the first face, and ``[3, 4]`` is another crease made of one edge in the second face.
- ``creaseLengths = [4, 2]`` - ``4`` is the number of vertex indices of the first crease, and ``2`` is one of the second crease.
- ``creaseSharpness = [5, 5]`` - The sharpness of each crease is ``5``.
- ``creaseSharpnessLengths = [1, 1]`` - ``1`` is the length for which the first element of ``creaseSharpness`` is.
Here is a different example to define creases with per-edge sharpness:
- ``creaseIndices`` - Same as above.
- ``creaseLengths`` - Same as above.
- ``creaseSharpness = [1, 4, 5, 3]`` - ``1``, ``4`` and ``5`` are the sharpness for the first, second and third edges in the first face, and ``3`` is in the second face.
- ``creaseSharpnessLengths = [3, 1]`` - ``3`` is the length of ``[1, 4, 5]`` in ``creaseSharpenss``, and ``1`` is the length of ``[3]``.
- * :kat:type:`int[]`
* :kat:attr:`geometry.creaseLengths`
* A list of the number of vertex indices of each crease. Each element in this array is the number of each group of `creaseIndices`
- * :kat:type:`float[]`
* :kat:attr:`geometry.creaseSharpness`
* A list of per-crease or per-edge sharpness.
- * :kat:type:`int[]`
* :kat:attr:`geometry.creaseSharpnessLengths`
* A list of the length of sharpnesses associated with a crease.
- * :kat:type:`int[]`
* :kat:attr:`geometry.cornerIndices`
* A list of vertex indices to corners to be creased.
- * :kat:type:`float[]`
* :kat:attr:`geometry.cornerSharpness`
* A list of sharpness for corners.
- * :kat:type:`int[]`
* :kat:attr:`geometry.holePolyIndices`
*
- * :kat:type:`float[]`
* :kat:attr:`geometry.point.Pref`
*
- * :kat:type:`group`
* :kat:attr:`geometry.point`
* See polymesh_.
- * :kat:type:`group`
* :kat:attr:`geometry.poly`
* See polymesh_.
- * :kat:type:`group`
* :kat:attr:`geometry.vertex`
* See polymesh_.
``pointcloud``
~~~~~~~~~~~~~~
Point cloud geometry. A point cloud is the simplest form of geometry and only
requires point data to be specified.
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`group`
* :kat:attr:`geometry.point`
* See polymesh_.
``nurbspatch``
~~~~~~~~~~~~~~
NURBS patch geometry. NURBS patches are a special type of geometry, quite
different from conventional mesh types. A NURBS curve is defined by its order,
a set of weighted control points and a knot vector.
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`int`
* :kat:attr:`geometry.uSize`
:kat:attr:`geometry.vSize`
* The size.
- * :kat:type:`float[4n]`
* :kat:attr:`geometry.point.Pw`
* List of control points and their weights, in the order: x y z w.
- * :kat:type:`int`
* :kat:attr:`geometry.u.order`
:kat:attr:`geometry.v.order`
* The order.
- * :kat:type:`float`
* :kat:attr:`geometry.u.min`
:kat:attr:`geometry.u.max`
* Parameters defining the NURBS patch.
- * :kat:type:`float[]`
* :kat:attr:`geometry.u.knots`
:kat:attr:`geometry.v.knots`
* Knot vector, a sequence of parameter values.
- * :kat:type:`group`
* :kat:attr:`geometry.trimcurves`
* Parameters defining the NURBS patch.
``curves``
~~~~~~~~~~
For creating groups of curves parented to the same transform. Curves cannot be
created by the UI but can be created through the Python API.
The following XML is from a scene graph that creates 3 linear curves
with 3 segments:
.. code-block:: xml
<attr type="GroupAttr" inheritChildren="false">
<attr type="IntAttr" name="degree" tupleSize="1">
<sample value="1 " size="1" time="0"/>
</attr>
<attr type="FloatAttr" name="knots" tupleSize="1">
<sample value="0.0 " size="1" time="0"/>
</attr>
<attr type="IntAttr" name="numVertices" tupleSize="1">
<sample value="4 4 4 " size="3" time="0"/>
</attr>
<attr type="GroupAttr" name="point" inheritChildren="false">
<attr type="FloatAttr" name="P" tupleSize="3">
<sample value="0.2 0 5 -2.8 0 2.0 0.5 0 1.0 -0.3 0 -1.5 1.8 0
4.9 -0.4 0 2.2 2.5 0 1.0 1.6 0 -1.4 3.8 0 4.9
1.6 0 2.2 4.5 0 1.0 3.6 0 -1.4"
size="36" time="0"/>
</attr>
</attr>
</attr>
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`int`
* :kat:attr:`geometry.basis`
* An integer indicating the curve basis. This is defined as follows:
- ``0`` - No basis
- ``1`` - Bezier
- ``2`` - B-Spline
- ``3`` - Catmull-Rom
- ``4`` - Hermite
- ``5`` - Power
This follows the ``BasisType`` enumeration in the Alembic library.
- * :kat:type:`float`
* :kat:attr:`geometry.constantWidth`
* A float that defines the width of a curve, which is applied uniformly
to each control point.
- * :kat:type:`int`
* :kat:attr:`geometry.degree`
* Specifies whether curves are linear (degree = 1) or cubic (degree = 3).
- * :kat:type:`float[]`
* :kat:attr:`geometry.knots`
* Knot vector is a sequence of parameter values.
.. note::
When splitting :kat:attr:`geometry.point.P` into multiple curves
using knots, the values in :kat:attr:`numVertices` must correspond.
For example, given 8 control points in
:kat:attr:`geometry.point.P`, ``degree = 3``, and
``knots = [ 0 0 0 0 1 1 1 1 0 0 0 0 1 1 1 1 ]``, then
``numVertices = [ 4 4 ]``.
- * :kat:type:`int`
* :kat:attr:`geometry.vstep`
* Sets the vertex stride for the curve. This is used by Katana to
calculate the expected length of point-scoped arbitrary attribute
arrays.
- * :kat:type:`int[]`
* :kat:attr:`geometry.numVertices`
* The number of vertices in each curve.
The :kat:attr:`numVertices` list defines the index ranges of the knots
used by each curve.
- * :kat:type:`float[3n]`
* :kat:attr:`geometry.point.P`
* List of points. The geometry points are unique floating point positions
in object space coordinates (x, y, z). Each point is only stored once
but it may be indexed many times by the same knot.
- * :kat:type:`float[3n]`
* :kat:attr:`geometry.point.orientation`
* List of orientations for each control point in the curve, relative to
the camera.
- * :kat:type:`float[n]`
* :kat:attr:`geometry.point.width`
* List of widths (diameters) of the curve at each control point.
.. note::
If both :kat:attr:`geometry.constantWidth` and
:kat:attr:`geometry.point.width` are set, the values in
:kat:attr:`geometry.point.width` are used.
- * :kat:type:`float[n]`
* :kat:attr:`geometry.arbitrary.width.value`
* List of widths (diameters) of the curve if the scope is not `point` or `primitive`. See :doc:`ArbitraryAttributes`.
.. note::
If both :kat:attr:`geometry.point.width` and
:kat:attr:`geometry.arbitrary.width` are set, the values in
:kat:attr:`geometry.point.width` are used.
.. note::
If both :kat:attr:`geometry.constantWidth` and
:kat:attr:`geometry.arbitrary.width` are set, the values in
:kat:attr:`geometry.arbitrary.width` are used.
``locator``
~~~~~~~~~~~
Used only in the Viewer; ignored by the renderers.
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`group`
* :kat:attr:`geometry.point`
* See polymesh_.
- * :kat:type:`group`
* :kat:attr:`geometry.poly`
* See polymesh_.
``sphere``
~~~~~~~~~~
Built-in primitive type for a sphere, supported by some renderers.
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`double`
* :kat:attr:`geometry.radius`
* The radius of the sphere.
``spheres``
~~~~~~~~~~~
A more efficient way of creating a group of spheres in PRMan at once. This is
ignored by other renderers.
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`float[3n]`
* :kat:attr:`geometry.point.P`
* List of points that represent the sphere centers.
- * :kat:type:`float[n]`
* :kat:attr:`geometry.point.radius`
* The spheres' radii.
- * :kat:type:`float`
* :kat:attr:`geometry.constantRadius`
* Can be used instead of :kat:attr:`geometry.point.radius` to specify a
single radius for all spheres.