Overview

The rosemath library contains functions to read and write mesh data as XML elements. The STEP and IFC faceting libraries use this XML as a baseline and may add additional information to describe product and assembly structure.

Meshes, Faces, and Facets

The shell element contains a single RoseMesh. There is an element that contains all of the vertices, and then a list of facet collections. If the facet set has no faces, all facets will be written as a single collection. If the facet set contains faces, a <facets> element will be written for each face and facets that do not belong to a face will not be written.

The XML for a simple mesh is shown below. The mesh is a box with eight vertices. The first two facets describe the bottom of the box and the surface normal at each vertex points down (-Z direction). Each facet references three vertices by index. Facets are connected when they share vertices. No faces are defined so all of the facets are written in one group.

<?xml version="1.0" encoding="UTF-8" ?>
<shell id="id123030" color="a1a14f">
<verts>
    <v p="-1 -2 -3"/>
    <v p="5 -2 -3"/>
    <v p="5 6 -3"/>
    <v p="-1 6 -3"/>
    <v p="-1 -2 7"/>
    <v p="5 -2 7"/>
    <v p="5 6 7"/>
    <v p="-1 6 7"/>
</verts>
<facets>
    <f v="0 3 2">
        <n d="0 0 -1"/>
        <n d="0 0 -1"/>
        <n d="0 0 -1"/>
    </f>
    <f v="2 1 0">
        <n d="0 0 -1"/>
        <n d="0 0 -1"/>
        <n d="0 0 -1"/>
    </f>

    [ ... more facets omitted ... ]

</facets>
</shell>

The structure above is written by rose_mesh_xml_save() and associated functions. This is available to any application that uses the mesh definitions in the rosemath library. The STEP and IFC faceting libraries add product and assembly data and use a different API to generate files with extra information.

The elements used for mesh data are described below:

shell

The shell element contains the faceted geometry of a shape. It contains the verts element with a list of vertices and facets elements with lists of facets. The following attributes may be used

• id — The identifier of the shell.
• color — Optional, color of the shell. Specified as a hexadecimal number in RGB format.

shell / verts

The verts elements contains the list of vertices in a shell. The element has no attrbiutes, and contains v elements, which define the vertices. There must be exactly one verts element within each shell.

shell / verts / v

The v element defines a single vertex. This is used to provide a cartesian point. The vertices are factored out, so that topological analysis of the shell can be performed. These vertices are identified by index in the facets. (e.g. the first v element is index 0, the second one is at index 1, etc.)

• p — The coordinates of a vertex, specified as a list of three numbers: x,y,z

shell / facets

The facets element is a container for a set of facets. There may be multiple facets elements within a shell. Each facets element defined the facets of a single face in the STEP data, and may override the color specified in the shell.

• color — The color of the contained facets. If given, this should be a hexadecimal number to the interpreted as RGB.

shell / facets / f

Each facet is repressented by an f element. The contains the vertices and normals that define the given facet.

• v — The vertex list. This is a list of three indexes into the verts element of the shell
• fn — A list of three numbers, giving a normalized direction vector for the normal of the facet as a whole. This value can be used for geometric analysis, but should not be used as a surface normal for drawing the facet if smooth shading is desired. (For that, use the vertex normals in the n elements)

shell / facets / n

The n element gives the surface normal at one of the three vertices of the facet. Each facet (f element) will have exactly 3 n elements corresponding to the vertices in the same order given in the v attribute.

• d — A list of three numbers, giving a normalized direction vector for the normal of the facet as a whole.

Product and Assembly Structure

The elements below describe how the XML document is extended to include STEP and IFC product structure and assembly information. The rosemath library does not provide functions to parse or write these. The STEP faceting library and the IFC faceting library have functions and applications to write additional data.

step-assembly

The root element in a STEP assembly XML file is the step-assembly element. This element has the following attributes:

• root — id of the root product in the file

product

The product element identifes a single STEP product STEP data. This corresponds to a step product_definition instance. There may be multiple products in the file nested within each other to give the assembly tree of the model.

• id — Identifier of the product
• step — URL for a STEP file referencing this product
• name — Name of the product (for display purposes)
• shape — ID of the shape of this product
• children — ID list of the child products in the assembly tree

shape

The shape element defines a single shape in the STEP data. It corresponds to an instance of a shape_representation. Like product elements, shape elements may have child elements, which represents the assembly tree. This means that there may be some redundant object hierarchy prepresented in the shape and product elements. This complexity is due to the way the STEP handles assemblies. Generally, the product tree should be used to label and identify object, and then the shape objects should be traversed to get the geometry.

• id — The identifer of the shape
• shell — The identifer of the shell containing the geometry of this shape

shape / child

The child element is used to specify a child shape and a transformation matrix for the child coordinate system.

• ref — The identifier of the child shape
• xform — An array of 16 numbers giving the transformation matrix to be applies to the child shape relative to the parent. This matrix is specified in the standard OpenGL column-major order.

shell or shell stub

A shell element is mesh data as described above, while a shell stub element is a reference to a shell inanother file. This feature is used to split assemblies into multiple files, each of which can be loaded on demand. A shell may either be a proxy or it may contain the geometry. (The options to the authoring tools determine if a single file is created, or if multiple file are, with the geometry split out into separate files.)

• id — The identifier of the shell
• size — The number of facets in the shell. This can be used to estimate the cost of loading the data
• bbox — The geometric bounding box of the shell. This is a list of 6 numbers: minx miny minz maxx maxy maxz
• href — A URL to the geometry. This should point to an XML file with a (non-stub) shell as its root element. If this URL is relative, it should be interpreted relative to the file containing the element (thus allowing an entire directory representing a STEP data set to generated without regard of where it will eventually be hosted.