STEP Unit Helper 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_tag_units(). Once the units are tagged, the stix_get_unit_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_get_unit_name() or stix_get_unit_fullname().

stix_get_const_unit()

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

The stix_make_unit() 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_get_measure_type()

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

RoseMeasureType stix_get_measure_type (RoseUnit u);

The stix_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_tag_units() 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_get_unit_fullname()

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

const char * stix_get_unit_fullname (RoseUnit u);

The stix_get_unit_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_get_unit_type() to find the unit enum and passes that to rose_get_unit_fullname()

stix_get_unit_name()

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

const char * stix_get_unit_name (RoseUnit u);

The stix_get_unit_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_get_unit_type() to find the unit enum and passes that to rose_get_unit_name()

stix_get_unit_type()

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

RoseUnit stix_get_unit_type (const char * lookup_by_name);

The stix_get_unit_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_tag_units() 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_make_named_unit()

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

The stix_make_named_unit() function is a wrapper around stix_make_unit() 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_make_unit()

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

The stix_make_unit() 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_make_named_unit() is a wrapper that casts the pointer to a named_unit type for more convenient use with geometric contexts.

stix_merge_units()

unsigned stix_merge_units (RoseDesign * d);

The stix_merge_units() 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_tag_units(d);

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

unsigned modcnt = stix_merge_units(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_put_const_unit()

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

The stix_put_const_unit() 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_get_const_unit() for that enum value.

stix_tag_units()

void stix_tag_units (RoseDesign * d);

The stix_tag_units 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_get_unit_type() and stix_get_value_type() functions.