Module objects 

Objects of a shape

Objects, in Fornjot parlance, are the elements that make up shapes. An object can be simple and just contain data (like Vertex, for example), or they can be quite complex and refer to other objects (which is actually most of them).

Object Identity vs Object Equality

Two objects are equal, if they contain the same data. For example, two instances of Vertex are equal, if they have the same position. This doesn’t mean those objects are identical. They might have been created by different pieces of code. Or maybe by the same piece of code, but at different times, maybe even based on different inputs.

This distinction is relevant, because non-identical objects that are supposed to be equal can end up being equal, if they are created based on simple input data (as you might have in a unit test). But they might end up slightly different, if they are created based on complex input data (as you might have in the real world).

An Example

Let’s talk about a specific example: two simple curves (straight lines that are coincident with coordinate system axes) which are intersecting at a simple point. Let’s say the intersection point sits at the global origin ([0, 0, 0]), and its local coordinate on each line also happens to be 0.

If you compute the global coordinates from each of the line-local coordinates, you’ll end up with the same result for sure. If we create two Vertex instances from these global coordinates, any validation code that expects those two instances to be equal, will be happy.

But what if the situation is not so simple? Let’s say the curves are circles instead of lines, and instead of being all neat, they are at some arbitrary location in space, oriented at weird angles. The local coordinates of their intersection point are not 0, but different values that are not neatly represented by floating point values.

In such a situation, you have an excellent chance of ending up with slightly different global coordinates, if you compute them from each local coordinate. If you’re building a Cycle, and this intersection point is where the two curves connect, you could end up with a gap (or self- intersection) in the cycle. If that ends up exported to a triangle mesh, that mesh will be invalid.

Validation Must Use Identity

To prevent such situations, where everything looked fine during development, but you end up with a bug in production, any validation code that compares objects and expects them to be the same, must do that comparison based on identity, not equality. That way, this problem can never happen, because we never expect non-identical objects to be the same.

For our example, this would mean we compute one Vertex from one of the local coordinates.

How Identity Works

We can exactly determine the identity of an object, thanks to centralized object storage. If objects are created at different times, potentially by different code, they end up being stored at different memory locations, regardless of their (non-)equality.

If you have two Handles, you can compare the identity of the objects they point to using the id method.

Implementation Note

As of this writing, most objects are not managed in the centralized object storage. Changing this is an ongoing effort (#1021).

Structs

Bare

Implementation of Form for bare objects

BehindHandle

Implementation of Form for objects behind a handle

Cycle

A cycle of connected half-edges

Face

A face of a shape

FaceSet

A collection of faces

GlobalEdge

An undirected edge, defined in global (3D) coordinates

HalfEdge

A directed edge, defined in a surface’s 2D space

ObjectSet

A graph of objects and their relationships

Objects

The available object stores

Shell

A 3-dimensional closed shell

Sketch

A 2-dimensional shape

Solid

A 3-dimensional shape, built from Shells. Many Solids will contains only one shell, but if the Solid contains cavities they will be represented by a shell each, as well as a shell for the outside.

Surface

A two-dimensional shape

Surfaces

Store for Surfaces

Vertex

A vertex, defined in global (3D) coordinates

WithHandle

Implementation of Form for objects that are paired with their handle

Enums

Handedness

The handedness of a face’s coordinate system

Object

An object

Traits

Form

The form that an object can take

Type Aliases

HalfEdgesOfCycle

An iterator over the half-edges of a Cycle