Overview

The following functions help to create and manage STEP context definitions.

All definitions are in the stix_context.h header file.

Three types of context objects appear in a typical STEP file. Each representation has a context that describes the units for geometry, the number of dimensions (2D or 3D) and possibly an uncertainty value for use when determining if two points are coincident (to avoid gaps in the geometry). The stix_make_geometry_context() function can create this data, while the stix_get_context_unit(), stix_get_context_angle_unit(), stix_get_context_length_unit(), stix_get_context_solid_angle_unit(), and stix_get_context_uncertainty() functions search contexts for information.

The products and product_definition objects also have a context that indicates the general type of information described by the file. These also refer to an application context, which describes the application protocol and general area of use. Typically, a file only has one AP context.

STEP files sometimes contain repeated context information, such as three or four geometry contexts that declare the same units and possibly the same uncertainty values. The stix_merge_ap_contexts(), stix_merge_product_contexts(), and stix_merge_rep_contexts() functions can analyze a file and combine duplicate contexts.

stix_get_ap_context()

stp_application_context * stix_get_ap_context(
        RoseDesign * d
        );

The stix_get_ap_context() function returns the first AP context in the file.

stix_make_ap_context()

stp_application_context * stix_make_ap_context(
        RoseDesign * d,
        StplibSchemaType ap = stplib_schema_none
        );

The stix_make_ap_context() function will create a new AP context or change an existing one to match the expected values for the AP specified in the second parameter. It is can be used when creating new data or when changing the schema of a file.

If the AP is omitted, the function will call stplib_get_schema() to find the schema associated with the design.

If a file has more than one AP context, this function just checks the first one. Use the stix_merge_ap_contexts() function to eliminate duplicates if necessary.

stix_get_context_angle_unit()

RoseUnit stix_get_context_angle_unit(
        stp_representation * rep
        );
RoseUnit stix_get_context_angle_unit(
        stp_representation_context * ctx
        );

The stix_get_context_angle_unit() function is a wrapper around the stix_get_context_unit() function that looks for a plane angle unit commonly found in geometric contexts. The stix_get_context_length_unit() and stix_get_context_solid_angle_unit() functions are also convenience wrappers.

stix_get_context_length_unit()

RoseUnit stix_get_context_length_unit(
        stp_representation * rep
        );
RoseUnit stix_get_context_length_unit(
        stp_representation_context * ctx
        );

The stix_get_context_length_unit() function is a wrapper around the stix_get_context_unit() function that looks for a length unit commonly found in geometric contexts. The stix_get_context_angle_unit() and stix_get_context_solid_angle_unit() functions are also convenience wrappers.

stix_get_context_solid_angle_unit()

RoseUnit stix_get_context_solid_angle_unit(
        stp_representation * rep
 	);
RoseUnit stix_get_context_solid_angle_unit(
        stp_representation_context * ctx
        );

The stix_get_context_solid_angle_unit() function is a wrapper around the stix_get_context_unit() function that looks for a solid angle unit commonly found in geometric contexts. The stix_get_context_angle_unit() and stix_get_context_length_unit() functions are also convenience wrappers.

stix_get_context_uncertainty()

stp_uncertainty_measure_with_unit * stix_get_context_uncertainty (
        stp_representation * rep,
        const char * uncert_name = 0
        );

stp_uncertainty_measure_with_unit * stix_get_context_uncertainty (
        stp_representation_context * ctx, 
        const char * uncert_name = 0
        );

The stix_get_context_uncertainty() function searches a geometric context and returns the return the first uncertainty of any type with a given name or the first length uncertainty if no name is given. The function returns NULL if none match or are present. Multiple uncertainties and uncertainties for things other than lengths are possible but not used in practice.

If a geometric context has an uncertainty value, it represents the distance below which two points are to be considered the same. This is an important concept when exchanging geometry because CAD systems work at different precisions. Knowing what the original system considered too small to distinguish lets a receiving system compensate for that, even if it works at a higher precision.

This precision value is usually marked by the name "DISTANCE_ACCURACY_VALUE" or "MODEL_ACCURACY" with the description "Maximum model space distance between geometric entities at asserted connectivities."

The following example code prints the numeric value of the uncertainty if one is present.

stp_representation * rep;
stp_uncertainty_measure_with_unit * umwu = 
        stix_get_context_uncertainty(rep);

if (umwu) 
        printf ("REP #%lu has uncert #%lu (%g %s)\n",
	    rep->entity_id(), umwu->entity_id(), 
	    stix_get_length_value(umwu),
	    stix_get_unit_name(umwu)
	);

stix_get_context_uncertainty_value()

double stix_get_context_uncertainty_value (
        stp_representation * rep,
        const char * uncert_name = 0
        );

double stix_get_context_uncertainty_value (
        stp_representation_context * ctx, 
        const char * uncert_name = 0
        );

The stix_get_context_uncertainty_value() function searches for a geometric uncertainty object using stix_get_context_uncertainty() and returns the numeric value. The function returns ROSE_NULL_REAL if none match or are present.

stix_get_context_unit()

RoseUnit stix_get_context_unit (
        stp_representation_context * ctx,
        RoseMeasureType mt
        );

RoseUnit stix_get_context_unit (
        stp_representation * rep, 
        RoseMeasureType mt
        );

The stix_get_context_unit() function examines a representation context and tries to find a unit definition of a particular type. If the context is not an instance of global_unit_assigned_context or if it does not contain a unit of the given type, the function returns roseunit_unknown.

The stix_get_context_angle_unit(), href=#stix_get_context_length_unit>stix_get_context_length_unit(), and stix_get_context_solid_angle_unit() functions are convenience wrappers for the units commonly found in geometric contexts.

stix_make_geometry_context()

stp_representation_context * stix_make_geometry_context(
        RoseDesign * design,
        const char * id,
        unsigned dims,
        stp_named_unit * len_unit,
        stp_named_unit * ang_unit,
        stp_named_unit * solid_ang_unit,
        double length_uncertainty = ROSE_NULL_REAL
        );

stp_representation_context * stix_make_geometry_context(
        RoseDesign * design,
        const char * id,
        unsigned dims,
        RoseUnit len_unit,
        RoseUnit ang_unit,
        RoseUnit solid_ang_unit,
        double length_uncertainty = ROSE_NULL_REAL
        );

stp_representation_context * stix_make_geometry_context(
        RoseDesign * design,
        const char * id,
        unsigned dims,
        RoseUnitSet units,
        double length_uncertainty = ROSE_NULL_REAL
        );

The stix_make_geometry_context() function creates a representation context for geometric information. Geometry contexts give the number of dimensions (usually 3), units for length, angle, and solid angle, and potentially a global uncertainty measure for comparing Brep point locations. This information is held by a single representation context object that is a complex instance of the following subtypes:

• geometric_representation_context
• global_unit_assigned_context
• global_uncertainty_assigned_context (if an uncertainty is given)

There are three overloaded versions of this function. The first takes pointers for the unit objects. The second takes RoseUnit enums for the units and creates them by calling stix_make_const_named_unit() The third takes a RoseUnitSet object and uses the length, angle, and solid angle fields within it.

stix_merge_ap_contexts()

unsigned stix_merge_ap_contexts (RoseDesign * d);

The stix_merge_ap_contexts() function merges repeated application context information in a file. After calling this function, a file will have at most one stp_application_context instance and at most one stp_application_protocol_definition instance.

The function returns the number of duplicates that were merged. If non-zero, call rose_empty_trash() to update the pointers and delete the duplicates.

stix_merge_product_contexts()

unsigned stix_merge_product_contexts(
	RoseDesign * d
	);

The stix_merge_product_contexts() function examines all product contexts, product definition contexts, and other application context elements in a file. If the attributes are the same (aside from upper/lower case differences) they will be merged. So they will be merged if two product contexts have the same "discipline_type", product definition contexts have the same "life_cycle_stage", or product concept contexts have the same "market_segment_type".

The function returns the number of duplicates that were merged. If non-zero, call rose_empty_trash() to update the pointers and delete the duplicates.

stix_merge_rep_contexts()

unsigned stix_merge_rep_contexts(
	RoseDesign * d
 	);

The stix_merge_rep_contexts() function examines all of the representation contexts in a file, moves duplicates to the trash and registers the primary context as a substitute. The function returns the number of duplicates that were merged. If non-zero, call rose_empty_trash() to update the pointers and delete the duplicates.

STEP files sometimes contain duplicate representation contexts, say three or four contexts that declare the same units and possibly the same uncertainty values. This function is used to compact that excess data down to a single context instance.

When merging contexts that are the same except for geometric uncertainty values, the function will merge uncertainties that are within 1% of each other, so 1.99E-5 and 2E-5 will merge with the slightly larger uncertainty (2E-5) surviving.

For non-geometric contexts (instances of the representation context supertype), the function will merge instances with matching context type fields. The context type field is ignored when combining the geometric context subtypes. The stix_merge_units() function performs a similar compaction for the unit definitions.

RoseDesign * d = ...

unsigned modcnt = stix_merge_rep_contexts(d);
if (modcnt) {
    printf ("Merged %d duplicate contexts\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.
}