Adding a New Primitive to BRL-CAD: Superellipsoid Walkthrough

The superellipsoid type ID is in include/rt/defines.h:

The same numeric value is the v5 BRL-CAD minor type in include/rt/db5.h:

For a new primitive, add a new ID_* value only after checking the existing range and comments in defines.h. Do not renumber existing IDs. If the new value extends the range, update ID_MAX_SOLID and ID_MAXIMUM consistently. Database minor type compatibility depends on these values remaining stable.

Every internal primitive structure starts with a magic value. The superellipsoid magic is in include/bu/magic.h:

The structure and checker macro live in include/rt/geom.h:

Use the same pattern for a new primitive. Put persistent fields in the internal struct and derived acceleration data somewhere else. The superellipsoid keeps precomputed ray-tracing values in a private struct superell_specific inside superell.c, not in rt_superell_internal, because the database only needs v, a, b, c, n, and e.

The superellipsoid has old database support in include/rt/db4.h:

That mapping is why rt_superell_import4 and rt_superell_export4 exist. A new primitive that never existed in v4 can normally leave ft_import4 and ft_export4 NULL in OBJ[]. If it must read legacy data, add explicit v4 record constants and field aliases and test old-file round trips.

rt_superell_parse in superell.c maps user-facing attribute names to fields:

This enables generic get, adjust, and form handling through the rt_generic_get, rt_generic_adjust, and rt_generic_form entries in OBJ[ID_SUPERELL]. For a new primitive, use a bu_structparse table when simple named fields are enough. Use a custom ft_get or ft_adjust only when generic struct parsing cannot express the data model.

Superellipsoid CPU ray tracing uses three core hooks:

rt_superell_prep checks that a, b, and c have non-zero length and are mutually perpendicular. It stores unit axes, inverse squared magnitudes, the center point, transformation matrices, a bounding sphere, and a bounding RPP. Those values go in stp→st_specific and are released by rt_superell_free.

For a new primitive, ft_prep should do all expensive invariant work once: validate database parameters, compute transform matrices, build acceleration data, set stp→st_center, stp→st_aradius, stp→st_bradius, stp→st_min, and stp→st_max, and return non-zero for invalid geometry. ft_shot should be as small as practical because it runs for every candidate ray. ft_norm should consume either the hit distance or cached per-hit data and return a unit normal.

The superellipsoid wireframe hook is rt_superell_plot. It builds three 16-point loops from V, A, B, and C with rt_superell_16pts and appends them to a bv_vlist. This is why draw superell.s can show an editable wireframe even though rt_superell_tess is currently a stub.

The superellipsoid also registers:

For a new primitive, implement ft_plot early. It gives MGED and other tools a visible object while more expensive features are still under development. Then add ft_bbox, ft_labels, and ft_keypoint when selection, snapping, object labels, and center-based operations need precise points.

The superellipsoid v5 external form is exactly fourteen network doubles: V, A, B, C, n, and e. rt_superell_import5 decodes them with bu_cv_ntohd, initializes an rt_superell_internal, and applies any modeling matrix through rt_superell_mat. rt_superell_export5 scales the length fields by local2mm, leaves n and e unscaled, and encodes the same fourteen doubles with bu_cv_htond.

The v4 hooks, rt_superell_import4 and rt_superell_export4, use union record, set s_type = SUPERELL, and place fields in s_values.

For a new primitive, write the v5 format first and make it boring. Keep a fixed order, convert only dimensional fields, use network byte order helpers, and make import initialize all rt_db_internal fields: idb_major_type, idb_type, idb_meth, and idb_ptr.

rt_superell_mat applies a matrix to v, a, b, and c, but intentionally does not change n and e. Tests in src/librt/tests/edit/superell.cpp document that global scale and rotation preserve those exponents.

rt_superell_volume uses an analytic formula when tgamma is available and a Cauchy-Crofton fallback otherwise. rt_superell_surf_area uses a numerical UV-space approximation and a special box-like case when both exponents are near zero. rt_superell_perturb creates a copied primitive and offsets the three axis lengths outward by a requested value.

For a new primitive, add measurement hooks when analyze, mass-property tools, or model validation need them. If you cannot implement an analytic measure, consider an existing fallback only when its assumptions fit the primitive.

rt_superell_brep starts from an ellipsoid BREP, converts it to a NURBS surface, adjusts control point weights using n and e, and uses either one surface or eight surfaces depending on exponent values. This hook is optional, but without it BREP workflows and converters cannot represent the primitive directly.

rt_superell_mirror is wired through the legacy dispatcher in src/librt/primitives/mirror.c. It mirrors v, a, b, and c. The current implementation resets n and e to 1.0, which is an important historical detail: when adding a new primitive, decide deliberately how every field transforms. If a field is invariant, preserve it explicitly.

All core primitive behavior is advertised through OBJ[] in src/librt/primitives/table.cpp. The superellipsoid entry is at ID_SUPERELL and has the label superell:

Also add RT_DECLARE_INTERFACE(superell) near the top of table.cpp; this declares the functions named by the table.

The table index must match the ID_* value. If your new ID introduces a gap, add placeholder entries so every later object keeps its existing index.

The superellipsoid demonstrates how most rt_functab slots are used. NULL means either the feature does not apply or the primitive has not implemented it.

EDOBJ[] is smaller than OBJ[], but it is just as important for applications that edit geometry interactively. The superellipsoid entry shows which hooks need primitive-specific behavior and which can remain generic or NULL.

The superellipsoid implements ft_edit_desc with a static rt_edit_prim_desc. It tells clients that superell has four interactive geometry commands, each with one scalar length parameter. For example, Set A uses a parameter named a, labeled Semi-Axis A, with type RT_EDIT_PARAM_SCALAR, minimum 1e-10, and units length.

This descriptor matters because newer clients can generate edit controls from metadata instead of hard-coding every primitive. When adding a new primitive, implement ft_edit_desc even if legacy MGED still needs hand-written menus. Then add it to src/librt/tests/edit/edit_desc.cpp; the superellipsoid test checks that JSON for ID_SUPERELL contains "superell" and command id 35113.

rt_edit_superell_write_params emits editable text:

rt_edit_superell_read_params reads the same text, converts v, a, b, and c from local units to base units, and leaves n and e dimensionless. A new primitive should keep the write/read pair symmetrical and should not require users to preserve labels exactly when the numeric order is unambiguous.

src/libged/typein/typein.c handles in superell.s superell …​. The superellipsoid path includes:

superell_in allocates struct rt_superell_internal, sets the magic, copies V, A, B, C, and stores n and e. It multiplies only the first twelve numeric inputs by gedp→dbip→dbi_local2base.

src/libged/make/make.c handles make name superell. Its default superellipsoid is centered at the current origin with:

For a new primitive, add both paths if users should be able to create it interactively. Use in for exact parameter entry and make for a reasonable default object.

There is no dedicated public mk_superell helper in this tree. Superellipsoid tests and examples create one by filling rt_superell_internal and calling wdb_export or wdb_put_internal. If a new primitive needs a public creation helper, add it to libwdb and public headers deliberately; otherwise document the internal-object creation pattern.

MGED still has hard-coded primitive editing in addition to EDOBJ[]. Superellipsoid appears in these places:

This is duplicated with some of the newer librt edit behavior. When adding a new primitive, check both systems. If MGED should edit the primitive today, add the legacy cases. If a newer GUI consumes EDOBJ[], add the structured edit descriptor and tests as well.

Archer has a superellipsoid edit frame:

For a new primitive, add GUI code only where the application cannot use the structured edit descriptor. If a custom frame is needed, follow the superellipsoid pattern: parse existing object data, expose primitive-specific fields, call put or edit commands to update the object, and list the Tcl file and icon in CMake.