STEP Unit Functions

Overview

The STEP data model for units is very flexible, with entities covering the base SI units and units based on conversion factors or derived from multiple base units. For easier use, the functions described below analyze the STEP data and mark common units using the unit enums provided by the ROSE Math library.

All definitions are in the stix_unit.h header file.

The RoseUnit enumeration identifies commonly used units, and simplifies reasoning with STEP unit descriptions. Before these can be used, the units in a file must be recognized and annotated with stix_unit_tag(). Once the units are tagged, the stix_unit_get_type() function returns the unit enum value for unit, measure, and geometry context data types. The measure functions also take unit enums to request values converted to specific units. There is also a RoseUnitSet class that holds a collection of units for all of the different types of quantities.

You can get the brief or full names for a unit with stix_unit_get_name() or stix_unit_get_fullname().

stix_unit_get_const()

RoseObject * stix_unit_get_const(
    RoseDesign * design, 
    RoseUnit ut
    );

The stix_unit_make() function searches a design for the STEP instance corresponding to a particular RoseUnit enum value. Since the STEP instance might be of type named_unit or derived_unit, the function returns a pointer of the more general RoseObject type.

stix_unit_get_fullname()

const char * stix_unit_get_fullname (stp_unit * u);
const char * stix_unit_get_fullname (stp_named_unit * u);
const char * stix_unit_get_fullname (stp_derived_unit * u);

const char * stix_unit_get_fullname (RoseUnit u);

The stix_unit_get_fullname() function returns a formal name for the unit, such as "millimetere". There are several overloaded versions of this function for the different types of unit values. This is simply a wrapper that calls stix_unit_get_type() to find the unit enum and passes that to rose_get_unit_fullname()

stix_unit_get_measure_type()

RoseMeasureType stix_unit_get_measure_type (stp_unit * u);
RoseMeasureType stix_unit_get_measure_type (stp_named_unit * u);
RoseMeasureType stix_unit_get_measure_type (stp_derived_unit * u);
RoseMeasureType stix_unit_get_measure_type (stp_measure_with_unit * mwu);

RoseMeasureType stix_unit_get_measure_type (RoseUnit u);

The stix_unit_get_measure_type() function returns the RoseMeasureType enum value that describes the type of quantity for a unit or measure. There are several overloaded versions of this function for the different types of STEP unit data objects. If given a measure object, this function will extract the unit description from it.

This function expects the units to have been previously recognized and tagged with the stix_unit_tag() function. It will return rosemeasure_unknown if the units have not been tagged or if the unit described by the data object was not recognized.

The version that takes a unit enum is simply an for rose_get_measure_type()

stix_unit_get_name()

const char * stix_unit_get_name (stp_unit * u);
const char * stix_unit_get_name (stp_measure_with_unit * mwu);

const char * stix_unit_get_name (RoseUnit u);

The stix_unit_get_name() function returns a concise name for the unit, such as "mm". There are several overloaded versions of this function for the different types of unit values. This is simply a wrapper that calls stix_unit_get_type() to find the unit enum and passes that to rose_get_unit_name()

stix_unit_get_type()

/* Find unit enum for a data object */
RoseUnit stix_unit_get_type (stp_unit * u);
RoseUnit stix_unit_get_type (stp_named_unit * u);
RoseUnit stix_unit_get_type (stp_derived_unit * u);
RoseUnit stix_unit_get_type (stp_measure_with_unit * mwu);

RoseUnit stix_unit_get_type (const char * lookup_by_name);

The stix_unit_get_type() function returns the RoseUnit enum value identifying a unit. There are several overloaded versions of this function for the different types of unit data objects. If given a measure object, this function will extract the unit description from it.

This function expects the units to have been previously recognized and tagged with the stix_unit_tag() function. It will return roseunit_unknown if the units have not been tagged or if the unit described by the data object was not recognized.

The overloaded that takes a string name is simply an alias for rose_get_unit().

stix_unit_make()

RoseObject * stix_unit_make(
	RoseDesign * d,
	RoseUnit ut
	);

The stix_unit_make() function returns the STEP instance corresponding to a particular RoseUnit enum value. The function returns an existing instance if one is present, otherwise it creates one. Since the STEP instance might be of type named_unit or derived_unit, the function returns a pointer of the more general RoseObject type.

The stix_unit_make_named() is a wrapper that casts the pointer to a named_unit type for more convenient use with geometric contexts.

stix_unit_make_named()

stp_named_unit * stix_unit_make_named(
	RoseDesign * d,
	RoseUnit ut
	);

The stix_unit_make_named() function is a wrapper around stix_unit_make() that casts the return value to the named_unit type for more convenient use with geometric contexts. The function will return null if you request a unit that is represented by the derived_unit type.

stix_unit_make_select()

stp_unit * stix_unit_make_select(
	RoseDesign * d,
	RoseUnit ut
	);

The stix_unit_make_select() function is a wrapper around stix_unit_make() that creates a unit definition and wraps it in the stp_unit SELECT type for more convenient use. Since the named unit and derived unit definitions do not share a common supertype, the select is used in many places in the STEP models that reference a unit.

stix_unit_merge()

unsigned stix_unit_merge (RoseDesign * d);

The stix_unit_merge() function examines all of the unit definitions in a file, moves duplicate definitions to the trash and registers the primary definition as a substitute. When STEP files contain duplicate unit definitions, such as three or four copies of a millimeter definition, you can use this function to eliminate the extras and simplify the file.

The function returns the number of duplicate units that were merged. If this is non-zero, then you must call rose_empty_trash() to update the pointers and delete the duplicates.

RoseDesign * d = ...

//----------------------------------------
// Tag units and contexts, de-duplicate them
stix_unit_tag(d);

// ... at some later point ...

unsigned modcnt = stix_unit_merge(d);
if (modcnt) {
    printf (Merged %d duplicate units\n, modcnt);
    rose_empty_trash();

    // Could call rose_update_object_references(d) instead
    // of emptying the trash.   Only updates pointers in one 
    // design and does not delete the trashed objects.
}

stix_unit_put_const()

void stix_unit_put_const(
	RoseDesign * design, 
	RoseObject * unit,
	RoseUnit ut
	);

The stix_unit_put_const() function takes a STEP instance describing a unit and a RoseUnit enum value. The function marks the instance as the one to be returned by stix_unit_get_const() for that enum value.

stix_unit_tag()

void stix_unit_tag (RoseDesign * d);

The stix_unit_tag function looks at each STEP unit definition in a file (si_units, conversion_based_units, context_dependent_units, and derived_units). It analyzes the unit description and associates a RoseUnit and RoseMeasureType enum value with it. The extra data is held in an associated StixMgrUnit object, but access is through the stix_unit_get_type() and stix_unit_get_measure_type() functions.