Configures near-zero separation and overlap classification for touching objects.

Distances are in metres and volumes in cubic metres. Contact requires separation no greater than distanceTolerance and, for pairs of closed solids, intersection volume no greater than maximumIntersectionVolume. The volume limit distinguishes contact from a penetrating intersection. Defaults allow 2 mm distance uncertainty and 1 mm3 overlap and report a separate result.

The map/JSON key treatment accepts the following values for the enabled contact check:

• ignore (Treatment::Ignore): omit contact reporting; contact alone does not count as a clash.
• clash (Treatment::Clash): report contact and count it as a clash.
• separate_result (Treatment::SeparateResult, default): report contact without counting contact alone as a clash.

Other enabled checks can still classify the same pair as a clash independently, including the intersection check when touchingCountsAsClash is enabled.

The map/JSON key degenerate_triangle_handling accepts:

• prevent_calculation (DegenerateTriangleHandling::PreventCalculation): report a geometry error for an object containing a degenerate triangle and omit calculations involving that object.
• ignore (DegenerateTriangleHandling::Ignore, default): skip zero-area triangles and calculate using the remaining valid triangles. Contact-area queries accept open surfaces; clash volume checks still require a closed, consistently oriented solid.

Contact-area queries treat non-solid surfaces as two-sided, allowing either winding of parallel faces. When either mesh is not a closed solid, maximumIntersectionVolume does not apply and no intersection volume or ratio is reported. Pairs of closed solids retain opposing-face and volume-limit checks.

include_contact_geometry (includeContactGeometry, default false) additionally returns contact patches as indexed triangle mesh objects for contact-area queries. Geometry is generated from the same non-overlapping clipping fragments as the area calculation. This increases response size and consumes geometric work units. Enabled contact checks in calculateClashes() also honor this option. The map/JSON key contact_geometry_output selects its destination:

• json (GeometryOutput::Json, default): return mesh data without changing the object structure.
• object_structure (GeometryOutput::ObjectStructure): create a new Design model named "Contact areas", add contact-surface objects to it, and return their IDs instead of mesh data. Requires include_contact_geometry to be true and source objects in the current project's object structure. Source geometry is unchanged. Objects are Object3d surfaces using the configured contact style. Source objects remain in their original models. Zero-area contacts create no objects; no model is created if every patch is empty. Creation runs only after a complete calculation; the model and all objects are staged before registration. Calculation or preparation failures leave the structure unchanged. Repeated calls create separate contact models. New objects have fresh IDs and retain their class-defined properties. Source properties, type assignments, links and relations are not copied. Their only assigned structure is the new contact model and configured style. Within each pair, geometrically equivalent A/B patches create one object. Equivalence compares coverage in both directions, independent of winding and triangulation, with numerical plane tolerance and relative area tolerance 1e-9. The contact distance tolerance is not used for deduplication.

style defines the style for newly created contact objects: string fields id, name and color. The default is { "id": "contact", "name": "ContactStyle", "color": #3aa5ff" }. Colors accept #rrggbb (opaque) or \#rrggbbaa (alpha last). Omitted style fields retain their current/default values. Object creation requires non-empty id/name and a valid color; invalid settings return 400. A repository style with matching ID, name and color is reused. A conflicting ID returns 409 without modifying that style. New styles are registered only when non-empty contact objects are published. JSON-only queries do not register styles; data.used_options includes the configured style in every mode. Degeneracy means the computed squared cross-product magnitude is zero. Invalid indices, non-finite coordinates or triangle areas, and meshes with no remaining triangles still produce errors. Skipping affects only the calculation cache, not the source mesh. Clash queries apply this policy to clearance preparation when contactEnabled is set. Intersection, coincidence and inclusion run independently and always skip zero-area triangles when preparing surfaces/containers. setFromMap() preserves omitted values and unrecognized enum strings. Numeric values must be finite and non-negative and satisfy the ranges above; map conversion does not validate these caller preconditions. Geometry is not evaluated here. Example: @code{.json} { "treatment": "separate_result", "degenerate_triangle_handling": "ignore", "include_contact_geometry": true, "contact_geometry_output": "json", "style": { "id": "contact", "name": "ContactStyle", "color": "#3aa5ff" }, "distance_tolerance": 0.002, "maximum_intersection_volume": 1e-9 } \endcode \par Contact-area calculation return value These options do not calculate geometry themselves. Project::calculateContactAreas() returns a core::ApiResponse; ToolsAPI::calcContactAreas() exposes it as JSON with status, message and data. Calculation status is 200 for complete results, 400 for invalid options, 206 for partial results, or 422 when geometry errors occur without any successfully evaluated candidate pair. The data object contains: - \c used_options: the effective ContactOptions map, including defaults for omitted fields. Also returned on errors; on validation or ID-resolution failure, it describes the settings prepared for the request. - \c results: one entry per reported contact pair. Selection indices are zero-based; object IDs are included when the meshes are repository objects. Self-pairs are skipped and symmetric pairs occur once. - \c errors: geometry or work-limit errors, with selection indices when available. - \c complete: false if any errors occurred; inspect this before interpreting an empty results list. - \c checked_pairs: successfully evaluated candidate pairs, including pairs without contact. - \c failed_pairs: candidate pairs whose geometric evaluation failed; mesh preparation errors are separate. Each contact result contains \c types (contact), \c is_clash (true only for treatment clash), \c surface_distance in metres and closest points \c point_a / \c point_b as world-coordinate [x, y, z] arrays. \c contact_area_a and \c contact_area_b measure covered area on each mesh in square metres; \c contact_area is their arithmetic mean, so an ordinary shared interface is counted once. Point/edge contacts and nonparallel faces can produce a contact result with zero area. \c inclusion_directions is empty for this contact-only query. \c volume_a / \c volume_b are present only for the corresponding closed solid. \c intersection_volume (cubic metres) and \c intersection_ratio (intersection volume divided by the smaller solid volume) require two closed solids. With include_contact_geometry enabled and contact_geometry_output set to json, \c contact_geometry_a and \c contact_geometry_b contain mesh objects on the respective source surfaces, matching contact_area_a and contact_area_b. Their \c vertices arrays store flat world-coordinate triples [x0, y0, z0, x1, y1, z1, ...] in metres; \c triangles arrays store flat zero-based vertex-index triples [i0, i1, i2, ...], as in the geometry API. Separate clipping fragments are not welded. Mesh winding follows the source surface, corrected outward for closed solids. Generated clipping triangles that collapse to zero area at world-coordinate precision are discarded; all output modes measure area from the same remaining world-space triangles. This numerical cleanup is independent of degenerate_triangle_handling, which controls degenerate triangles in the input meshes. Zero-area contacts have empty arrays. With the option disabled, both geometry fields are omitted. The returned objects have no repository IDs; the pair's object_a_id/object_b_id identify the source objects. In object_structure mode, \c data.contact_model_id identifies the new model, and each result's \c contact_object_a_id / \c contact_object_b_id identify the new objects instead; these fields are absent for empty patches. Failed object preparation returns status 422 with complete false and an error message, even if geometric pair evaluation succeeded. \c contact_geometry_shared is true when both sides share one created object; contact_object_a_id and contact_object_b_id then contain the same ID. The area measurements for both sides remain available. Example response for two parallel open unit-square surfaces separated by 1 mm, using the options above: @code{.json} { "status": 200, "message": "", "data": { "used_options": { "treatment": "separate_result", "degenerate_triangle_handling": "ignore", "include_contact_geometry": true, "contact_geometry_output": "json", "style": { "id": "contact", "name": "ContactStyle", "color": "#3aa5ff" }, "distance_tolerance": 0.002, "maximum_intersection_volume": 1e-9 }, "results": [ { "selection_a_index": 0, "selection_b_index": 0, "object_a_id": "surface-a", "object_b_id": "surface-b", "types": ["contact"], "inclusion_directions": [], "is_clash": false, "surface_distance": 0.001, "point_a": [0.0, 0.0, 0.0], "point_b": [0.0, 0.0, 0.001], "contact_area_a": 1.0, "contact_area_b": 1.0, "contact_area": 1.0, "contact_geometry_a": { "vertices": [0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 0, 0, 1, 1, 0, 0, 1, 0], "triangles": [0, 1, 2, 3, 4, 5] }, "contact_geometry_b": { "vertices": [0, 0, 0.001, 1, 0, 0.001, 1, 1, 0.001, 0, 0, 0.001, 1, 1, 0.001, 0, 1, 0.001], "triangles": [0, 1, 2, 3, 4, 5] } } ], "errors": [], "complete": true, "checked_pairs": 1, "failed_pairs": 0 } } \endcode To create a contact model and objects instead of returning mesh data, use these geometry options (other settings retain defaults): @code{.json} { "include_contact_geometry": true, "contact_geometry_output": "object_structure" } \endcode Result entries then contain, for example, "contact_object_a_id": "new-contact-a" and "contact_object_b_id": "new-contact-b" instead of contact_geometry_a/contact_geometry_b.

ToolsAPI ID resolution can return 204 for an empty selection, 404 when no IDs are found in a selection, 206 for missing or duplicate IDs, or 400 for incompatible objects before calculation; these responses contain used_options but no calculation results. Enabled contact checks in clash queries include these contact-area fields alongside other classifications. In object-structure mode, earlier check failures suppress creation and set data.contact_geometry_creation_skipped true while retaining numeric contact results.

Since

1.1, 09/2026