[SESI logo]

Houdini Development Toolkit - Version 6.5

Side Effects Software Inc. 2004

Geometry

Faces (Polygons and Curves)

A face is a generic term describing open or closed polygons, NURBS (Non Uniform B-Splines) curves, and Bezier curves. NURBS and Bezier curves belong to a class of curves called Splines.

Basic Functionality

The common functionality of all three face types is reflected in the base class, GEO_Face:
  • virtual int insertVertex(GEO_Point *ppt, unsigned int where=0)
  • virtual int appendVertex(GEO_Point *ppt);
  • virtual int deleteVertex(GEO_Vertex &vtx);
  • virtual int deleteVertex(unsigned int num);
    These methods insert and delete a vertex specified by a GEO point or vertex, or by a vertex index. The Spline classes derive methods to adjust the basis accordingly. The vertex index is returned upon successful completion. If the operation fails, it returns -1.

  • void setSize(unsigned int newsize)
    Adjust the size of the vertex array. This method does not adjust the Spline basis.

  • int find(const GEO_Vertex &vtx) const
  • int find(const GEO_Point &ppt) const
    Find the index of a given vertex. Return -1 if not found.

  • const GEO_Vertex &operator()(unsigned i) const
  • GEO_Vertex &operator()(unsigned i)
  • const GEO_Vertex &operator[](unsigned i) const
  • GEO_Vertex &operator[](unsigned i)
    These are subscript operators. The [] operator will create the vertex if the index does not exist.

  • unsigned isClosed()
  • virtual void close(int rounded = 1, int preserveshape = 0)
  • virtual void open(int preserveshape = 0, int safe = 0)
    Query the closed/open state of the face, or set it. The rounded and shape preservation options are meaningful for the Spline curves.

  • virtual void reverse()
    Reverse the face's vertices and its basis too, if necessary.

  • virtual int cycle(int amount, int = 1)
    Shift the array of vertices by an offset and wrap around. The offset can be either negative or positive.

  • virtual int unroll(void)
    Assuming the face is closed, "unroll" it so that the CVs that are shared to form a wrapped curve are made unique. Also, the face becomes open. If the face is not closed, the method returns -1. Otherwise it returns 0.

  • virtual int removeRepeatedVertices(int check_order = 0)
  • virtual int removeRepeatedPoints(float tol = 0.001F, int check_order = 0)
    Remove all consecutively repeated vertices.


  • Parametric Operations

    To enable a transparent use of all three face types in a parametric fashion, we define an implicit domain for the polygon type and use the basis domain for the curve types. The size of the polygonal domain is given directly by the number of polygon vertices.

    The following is a list of parametric (domain oriented) methods shared by all face types:

  • virtual unsigned getOrder(void) const
    Return the order (degree+1) of the underlying basis. Since a polygon is inherently linear, its order is always 2. A valid Spline basis order ranges between 2 and 11.

  • virtual int evaluatePoint (UT_Vector4 &pos, float u_unit, float=0, unsigned du=0, unsigned = 0) const
  • virtual int evaluatePointWAttrib(UT_Vector4 &pos, GB_AttributeData &adata, const GB_FloatOffsets &foffsets, float u_unit, float=0, unsigned du = 0, unsigned = 0) const
    Evaluate the position or the derivative at domain point (u,v), where u and v must be in the [0,1] interval. "v" and "dv" are ignored. Return 0 if OK and -1 otherwise. The second method evaluates the float attributes whose offsets are provided in the GB_FloatOffsets array.

  • virtual float unitToRealDomain(float u_unit) const
  • virtual float realToUnitDomain(float u_real) const
    Go from a normalized domain ([0,1]) to the real domain or vice versa.

  • virtual void validInterval(int &a, int &b) const
    Return the bounds of the valid evaluation interval in domain space. For polygons this refers to CV indices. Curves use the knot indices to determine these values.

  • virtual int refine (float k, int=0)
  • virtual int refineWAttrib (float k, const GB_FloatOffsets &foffsets, int=0)
    Change the multiplicity of the domain value by inserting it after checking its current multiplicity. Return -1 if invalid, otherwise return the index of the inserted knot.

  • void homogenize (int startcv = 0, int endcv = -1)
  • void dehomogenize(int startcv = 0, int endcv = -1)
  • void homogenizeWAttrib(const GB_FloatOffsets &foffsets, int startcv = 0, int endcv = -1)
  • void dehomogenizeWAttrib(const GB_FloatOffsets &foffsets, nt startcv = 0, int endcv = -1)
    Express the points in homogeneous coordinates or vice-versa. endcv can be greater than the number of vertices or smaller than startcv. In both cases we will wrap the index. The last two methods operate on attributes as well.

  • virtual void weights(unsigned short onoff)
    Turn CV weight checking on or off. While this method is irrelevant for polygons, it determines whether a spline is treated as a rational curve or not. Turning weights off will assume the curve is non-rational (all weights equal) in all subsequent operations. To find out is a curve is rational, use GEO_Curve::isRational().


  • The methods listed above are only a minimal subset of the functions available to you in the face classes. Other places of interest are GEO_Curve, which is the base class of NURBS and Bezier curves, GEO_PrimNURBCurve, GEO_PrimRBezCurve, GU_PrimPoly, GU_Curve, GU_PrimNURBCurve, and GU_PrimRBezCurve.

    Class Instantiation

    The only non-abstract face classes are GU_PrimPoly, GU_PrimNURBCurve, and GU_PrimRBezCurve. Although they all have constructors, we recommend that you use the static ::build() methods defined in each class instead. This way the objects will be properly initialized.

    All ::build() methods require a pointer to the primitive container (GU_Detail) and a number of points. The closed/open flag is optional, as is the option to create GEO_Points. By default, a GEO_Point is created for each vertex.

    Here is an example of how to build a face of each type:

    GU_Detail gdp; GU_PrimPoly *poly; GU_PrimNURBCurve *nurbcurve; GU_PrimRBezCurve *beziercurve; // // Build a closed polygon with 10 CVs: // poly = GU_PrimPoly::build(&gdp, 10, GU_POLY_CLOSED); // // Build a NURBS curve with 10 CVs, order 4 (i.e. cubic), open, and // clamped. A clamped NURBS curve is one that touches its end CVs. // nurbcurve = GU_PrimNURBCurve::build(&gdp, 10, 4, 0, 1); // // Build a Bezier curve with 10 CVs, order 4 (i.e. cubic) and open: // beziercurve = GU_PrimRBezCurve::build(&gdp, 10, 4, 0); // // Since the faces were built with automatically generated GEO_Points, // we can assign coordinates to those points as follows: // for (int i = 0; i < poly->getVertexCount(); i++) (*poly)(i).getPos().assign(i,0,0,1); // // To build a face without automatically generated GEO_Points, add one // more parameter to the build() method and set it to 0: // poly = GU_PrimPoly::build(&gdp, 10, GU_POLY_CLOSED, 0); // // Points need to be created and assigned to the vertices explicitly: // GEO_Point *ppt; for (int i = 0; i < poly->getVertexCount(); i++) { ppt = gdp.appendPoint(); *ppt = UT_Vector4(i,0,0,1); (*poly)(i).setPt(ppt); } Always check the result of the ::build() method for failure. A face will not be created unless given valid parameters. A Bezier curve, for example, is particularly strict about the number of CVs for a given basis order.

    NURBS and Bezier curves are built with uniform bases in a [0,1] domain. The size and the parameterization of the domain can be changed with GEO_Curve::reparameterize() or by accessing the basis pointer directly with GEO_Curve::getBasis().


    Table of Contents
    Operators | Surface Operations | Particle Operations | Composite Operators | Channel Operators
    Material & Texture | Objects | Command and Expression | Render Output |
    Mantra Shaders | Utility Classes | Geometry Library | Image Library | Clip Library
    Customizing UI | Questions & Answers

    Copyright © 2004 Side Effects Software Inc.
    477 Richmond Street West, Toronto, Ontario, Canada M5V 3E7