Three layers: a Rust model that knows the document, timeline and features but no geometry; a thin C++ facade over Open CASCADE Technology (OCCT) that does the geometry; and a Qt application that talks to the model with JSON commands.
Sketch drawing tools attach their live value editors to dimension previews built from temporary geometry. The overlay uses the placed dimension renderer for their extension lines, arrows and sectors; typed values continue to reach the model through the existing sketch commands.
The chat's Rust protocol adapter classifies account failures separately from failed model tools. The application keeps a known account failure until an explicit sign-in check and a bounded, context-free probe succeed; the probe cannot use the document's tools or replace its conversation.
| Part | Language | Responsibility |
|---|---|---|
core/model (mitcad-model) |
Rust | Document, timeline, features, parameters and expressions, units, sketches, topological naming, cached recompute, undo, design file, design comparison. No OCCT. Its testing feature gives other crates' tests the mock kernel (testing, the crate mitcad-model-testkit) and the shared fixtures (test_support). |
core/solver (mitcad-solver) |
Rust | 2D constraint solver, the spatial point/line solver of 3D sketches and the joint solver of assemblies behind a narrow API (README). |
core/vec3 (mitcad-vec3) |
Rust | The [f64; 3] helpers (add, sub, dot, cross, norm, the unit-vector variants) that the model, the solver and the readers share, and the same for [f64; 2] in its vec2 module; no dependencies, no vector type. |
core/f3d (mitcad-f3d) |
Rust | The .f3d reader's facade: re-exports the crates below under their old paths (mitcad_f3d::design::ir, mitcad_f3d::asm, ...), reads a document's body blobs, and has the test references, mitcad-f3d-inspect and the corpus tests. |
core/dump (mitcad-dump) |
Rust | The design dump IR of SCHEMA.md as Rust types, with the items' file states; written by the .f3d and .ipt readers, replayed by the import (README). |
core/asm (mitcad-asm) |
Rust | The ASM B-rep data of .f3d body blobs, .ipt B-rep records and .dwg solids (binary and text form, the history), a neutral B-rep model in millimetres with checks, and the conversion to it (README). |
core/f3d-names (mitcad-f3d-names) |
Rust | The names that faces and bodies of .f3d body blobs carry, and the faces, edges and vertices of a history state that feature inputs name by them (README). |
core/f3d-file (mitcad-f3d-file) |
Rust | The document inside an .f3d file's zip container (segments, body blobs, .f3z packages), its display meshes and its appearance asset packages (README). |
core/f3d-design (mitcad-f3d-design) |
Rust | The design segment of .f3d files (timeline, parameters, sketches, features, components) built into the dump IR from the decoded streams, with the feature inputs found in the bodies' ASM history; re-exports mitcad-f3d-decode's modules under their old paths (README). |
core/f3d-decode (mitcad-f3d-decode) |
Rust | The streams, object records, sketches, recipes and stored curves of the .f3d design segment decoded, below the feature building of mitcad-f3d-design (mitcad#779; README). |
core/expr (mitcad-expr) |
Rust | Parameter expressions with units: lexer, parser, evaluation, formatting, units and dimensions, parameter limits, the parameter table and the .f3d expression checks (README). No dependencies; the model re-exports it as mitcad_model::expr. |
core/print-keys (mitcad-print-keys) |
Rust | The print settings' key map: MitCad's printer, process and filament keys with their types, units, form places and, per slicer dialect, the slicer's key and value conversion (README). Re-exported as mitcad_model::print_keys. |
core/model-api (mitcad-model-api) |
Rust | The JSON command, query and preview API of a document, with its reference commands.md (README). Above the model (mitcad#777): the document's api methods are extension traits (DocumentApi, prelude). |
core/model-build (mitcad-model-build) |
Rust | The BUILD tab's planning: placing and editing parts, connectors, panels, timber members, joinery, spacing sets, frames, fasteners, the junctions and the cut list (README). Above the model, below the api (mitcad#777); what the design file keeps of BUILD stays in mitcad_model::build and is re-exported. The document's BUILD methods are extension traits (prelude). |
core/model-diff (mitcad-model-diff) |
Rust | Comparison of two designs or versions in the model's terms, for the version history (README). Above the model (mitcad#777); used by vcs and ffi. |
core/model-tests/<area> (mitcad-model-tests-<area>) |
Rust | The model's tests through the JSON api, a small crate per area (sketch, features, parts, assembly, joints, drawing, print, BUILD, the imports' tests that need the api, ...; ctest core.model.<area>), so that a new test recompiles only its own crate (README); support holds BUILD's test library. |
core/model-base (mitcad-model-base) |
Rust | Below the model's core (mitcad#777): the Kernel trait with the data it takes and gives (exchange options and meshes, drawing views, sheet metal charts, named segments), and the base data that needs nothing of the core: ids, topological names, profiles, datums, transforms, sweep and surface specifications, parameters, properties, configurations, appearances, render settings, the recompute monitor, fingerprints, hashes (README). The model re-exports every module at its old path (mitcad_model::kernel, mitcad_model::topo, ...). |
core/model-testkit (mitcad-model-testkit) |
Rust | The mock geometry kernel of the model's tests (MockKernel, MockShape) on mitcad-model-base alone, so that an edit in it rebuilds only test binaries (README). The model's own tests use it as a dev-dependency; its testing feature re-exports it as mitcad_model::testing. |
core/model-drawing (mitcad-model-drawing) |
Rust | The drawing layout and writers above the model (mitcad#777): sheets laid out with their views, dimensions, annotations, hole tables, bills of materials, frame and title block from a sheet template, written as PDF, SVG, DXF and DWG; the built-in templates and the template libraries; the projection cache (DrawingCache, in the document's side cache). What a design file keeps of a drawing stays in the model (core/model/src/drawing: def.rs, annotate_def.rs, tables_def.rs, template_def.rs), which this crate re-exports under the same paths (README). |
core/sketch (mitcad-sketch) |
Rust | The general sketch below the model's core (mitcad#780): 2D geometry, entities, constraints and dimensions, the solve, profile regions, projections, offsets, patterns, equal spacing, texts, fonts, QR codes, SVG and DXF drawings, the sketch edits (SketchEdit) and the sketch feature's definition (def.rs: SketchDef, SketchOutput), on mitcad-model-base, mitcad-expr, mitcad-solver and mitcad-dxf (README). The model re-exports it as mitcad_model::sketch and the definition as mitcad_model::features::sketch, where the feature's references, checks against the timeline and evaluation stay. |
core/import (mitcad-import) |
Rust | Replays .f3d dumps (also those core/ipt makes of .ipt parts) as MitCad commands, checked against the file's stored results (README): the replay's core (mitcad-import-replay) with its families (mitcad-import-joints, mitcad-import-sheet, mitcad-import-primitives, mitcad-import-appearances) put together, and the replay's tests (mitcad#785); .solidcraft designs through mitcad-import-solidcraft. Above core/model, not the api (mitcad#778): it asks the model for sheet states, joint frames and constraint rows directly, and runs the JSON commands a cut and paste needs through Options::commands, which core/ffi fills with the api's command (mitcad_import::Commands). |
core/import-base (mitcad-import-base) |
Rust | What the imports share: the import's Progress (one per process, for the watchdog, the memory guard and the kernel's cancel check), vector helpers, the bodies of one replay, planar faces, the candidate core, the notes' texts, the sketch helpers (README). No reader. |
core/import-ifc (mitcad-import-ifc) |
Rust | The IFC import: the building model as components, features and bodies (README). |
core/import-rvt (mitcad-import-rvt) |
Rust | The .rvt import: building elements as features and bodies, one component per level, with the IFC import's builder (README). |
core/import-fcstd (mitcad-import-fcstd) |
Rust | The FreeCAD import: structure, stored bodies, sketches, history and parameters, checked against FreeCAD's per-feature shapes (README). |
core/import-solidcraft (mitcad-import-solidcraft) |
Rust | The .solidcraft import: designs with their history built again as MitCad features, with an importer of its own (mitcad#785; mitcad-import re-exports it as solidcraft) (README). |
core/import-replay (mitcad-import-replay) |
Rust | The core of the .f3d dump replay: Importer's state, the timeline walk, references, the history check, fallbacks and the report (mitcad#785; mitcad-import re-exports its public paths). Reaches the families above it through its Families trait (README). |
core/import-joints (mitcad-import-joints) |
Rust | The replay's joints family above its core: joints, joint origins, captured positions, ground items and assembly relationships, as extension traits on the core's Importer (mitcad#785; README). |
core/import-sheet (mitcad-import-sheet) |
Rust | The replay's sheet-metal family above its core: sheet items as native sheet features, roundings and chamfers as sheet corners (mitcad#785; README). |
core/import-primitives (mitcad-import-primitives) |
Rust | The replay's primitives family above its core: boxes, cylinders, spheres, tori and coils placed on a plane (mitcad#785; README). |
core/import-appearances (mitcad-import-appearances) |
Rust | The replay's appearances family above its core: the file's appearances and physical materials on the replay's bodies, faces and occurrences, as an extension trait on the core's Importer; the report's types stay in the core (mitcad#791; README). |
core/freecad (mitcad-freecad) |
Rust | .FCStd reader: typed objects and properties, placements, links, sketches, spreadsheets, expressions. No geometry. |
core/zip (mitcad-zip) |
Rust | Zip container for .f3d and .FCStd (stored, deflate, zstd; a writer for tests). An entry inflates to at most 256 MiB unless the caller opts in to up to 4 GiB (body blobs, .f3z documents, large meshes), and never to more than 1032 bytes per compressed byte (mitcad#923). |
core/ipt (mitcad-ipt) |
Rust | .ipt part files: compound file container (MS-CFB), property sets (MS-OLEPS), the segment database, the B-rep record converted by core/asm, the meshes of mesh features, the definitions segment (parameters, sketches, features) and the bodies' and faces' appearances (the Protein package, read by core/f3d-file, mitcad#1367) as the import's dump IR, and .iam assemblies (referenced files, occurrences, placements; README). No geometry. |
core/ifc (mitcad-ifc) |
Rust | IFC files (IFC2X3, IFC4, IFC4X3; .ifczip): an own ISO 10303-21 reader, units, the spatial structure, products and their placements, relationships, styles, and the shapes' representation items decoded (profiles, swept solids, booleans, breps, face sets, mapped items; README). No geometry. |
core/solidcraft (mitcad-solidcraft) |
Rust | .solidcraft designs: the JSON document or its container, upgraded from any file format to one by SolidCraft's own steps (third_party/solidcraft), typed sketches and feature kinds, expressions in MitCad's language. No geometry. |
core/dxf |
Rust | DXF read and write. |
core/dwg (mitcad-dwg) |
Rust | .dwg drawings, R13 to R2018: the containers and their compression, header variables, classes, the object map, objects, the data storage; the 3D content (B-rep records parsed by core/asm, meshes, blocks and inserts) and the plan of components; the writer of 2D drawings in R2000 for the drawing export (mitcad#728) (README). No geometry. |
core/3dm (mitcad-3dm) |
Rust | .3dm models, format versions 5 to 8 (mitcad#1715): the chunks, the settings (units, tolerance), layers, block definitions and the object table with attributes; B-reps, extrusions, NURBS, plane, revolution and sum surfaces, the curve classes, meshes and block instances, SubD objects' control nets (as Form cages, mitcad#1757); their conversion to the neutral B-rep model of core/asm in millimetres; a writer of sample models for the tests (README). No geometry. |
core/3mf (mitcad-3mf) |
Rust | 3MF writer (one object of parts) and a checking reader for tests. |
core/gltf (mitcad-gltf) |
Rust | glTF 2.0 reader (mitcad#1826): the binary and JSON forms with their buffers and images embedded or beside them, the node tree, triangles with the texture coordinates of their images (mitcad#1862), metallic-roughness materials and their images, and in words what the import does not take; the model makes the mesh bodies and components (exchange/gltf_import.rs). MitCad's own glTF files come from the application's web page writer (app/web/WebGlb) (README). No geometry. |
core/serp (mitcad-serp) |
Rust | .serp files, format versions 1 to 9 (mitcad#1870): the bare JSON scene or its zip, units, layers with their paths and colours, objects with their B-rep data (OCCT's binary format, read by the kernel's import_brep) or meshes, blocks, and the kinds the import leaves out, counted; a newer version refused in words. The model makes the bodies, folders and block components (exchange/serp_import.rs) (README). No geometry. |
core/usdz (mitcad-usdz) |
Rust | USDZ writer: the binary USD layer (crate format 0.8.0, LZ4 and USD's integer coding written here, no USD library) of a scene of meshes, Xforms and UsdPreviewSurface materials, packed with its textures 64-byte aligned; time-sampled transforms of an animated scene (mitcad#1597); a checking reader for tests (#123). |
core/vcs (mitcad-vcs) |
Rust | Version history of projects in git (gitoxide, only here); remotes through the system's git; component libraries and community indexes in git repositories (libraries.md). |
core/update (mitcad-update) |
Rust | Release manifest, signatures, version selection; the mitcad-release tool. No network (updates.md). |
core/mcp (mitcad-mcp) |
Rust | MCP lifecycle, JSON-RPC envelopes, tool schemas, the command-reference resource and model_reference, the reference in sections (mitcad#714); the guides for agents (core/mcp/guide/, Agent Skills layout, behind model_reference {"guide": …} and mitcad://guide/<id>, mitcad#1508); headless stdio and live application profiles. No geometry dependency; its tests read the model API's permitted names (mcp.md). |
core/preview (mitcad-preview) |
Rust | Preview images without a GPU or a display (mitcad#1486): model_render's arguments, its camera (shared by every quality), a software rasterizer over the bodies' display meshes (with a section's caps and highlighted edges, mitcad#1487, and the overlay of an analysis' triangles over them, mitcad#1488) and a PNG writer; deterministic on one platform. The live server draws the same pictures through Document::mcp_render. The model builds the scene (core/model/src/preview.rs) (mcp.md, Preview images); its line art as SVG (mitcad#1736, format: "svg") is a drawing view's projection along the camera (core/model/src/preview/lines.rs). |
core/cam (mitcad-cam) |
Rust | CAM for CNC milling (mitcad#1013, cam.md): tools and the tool library, planar outlines of lines and arcs, toolpaths, the 2.5-axis operations (facing, contour with the tool radius compensation, offset pocketing with islands, drilling), the machine model with its keep-out zones and tool changers and the check of a program against it, and the post-processors (one PostProcessor trait; grbl, grblHAL, RepRapFirmware, MillenniumOS, Mach3, Mach4, LinuxCNC). No model, no OCCT; offsets by cavalier_contours. |
core/subdiv (mitcad-subdiv) |
Rust | Forms (mitcad#1757): control cages, their edits, Catmull-Clark subdivision with creases and boundaries and the limit surface as bicubic patches, below the model (re-exported as mitcad_model::subdiv); no OCCT (Forms). |
core/ffi (mitcad-ffi-bridges), core/cpp |
Rust, C++ | CXX bridges: the Kernel on OCCT, the document API for C++. An rlib (mitcad#792), so that Cargo starts it on its dependencies' metadata. |
core/ffi-staticlib (mitcad-ffi) |
Rust | The static library the application links (CMake target mitcad_ffi): mitcad-ffi-bridges with every Rust library it uses, no code of its own (README). |
geometry (mitcad_geometry) |
C++ | OCCT facade: profiles, features, booleans, name transfer, queries, file formats, ASM bodies, analyses. No Qt. |
tools/cli (mitcad-cli) |
C++ | Headless open/import, recompute, properties, export; kernel and import tests run through it. Also render (the final render through the render worker), which links Qt Core and Gui for the application's scene and job code. |
app |
C++/Qt, Objective-C++/AppKit | Shared document and command orchestration; the Qt desktop UI on every platform (macOS: macos-shared-qt.md); the paused AppKit frontend. |
tools/freecad-export |
Python, Bash | FreeCAD macros that make the FreeCAD import's reference models and dumps. |
Dependencies point one way: app → core/ffi → core/model-api → core/model-build, core/model-drawing → core/model (with
model-diff, solver, vec3, subdiv, f3d (over f3d-design, f3d-decode, f3d-file, f3d-names, asm, dump), import, freecad, zip, 3mf, usdz, vcs, ipt, ifc, solidcraft, dwg, expr, print-keys, import-base, import-ifc, import-rvt, import-fcstd, model-base, sketch; update
stands alone) and core/ffi → geometry → OCCT. The model reaches geometry only
through the Kernel trait, so model tests run on a mock kernel.
Each term has one meaning in the code, the UI and the docs:
| Term | Meaning | In the code |
|---|---|---|
| Design | One .mitcad file (a part or an assembly) |
Document::load_design, save_design (bridge), is_design_file, FileKind::Design |
| Project | A folder that is one git repository and holds designs and folders; Local or Cloud | Project, ProjectRepo, open_project, find_project, create_project |
| Folder | A folder inside a project | relative paths with / |
| Version | A recorded state of a design: one commit | commit, history, load_version |
| Owner | A user or an organisation on a git service (the first part of a Cloud address) | CloudAddress::owner |
| Projects panel | The panel of projects, folders and designs; the Browser is the design's feature tree | |
| Projects folder | The default parent of new projects (Documents/Mitcad) | projectsDirectory() (framework/AppSettings) |
JSON command and field names and the file formats' keys stay as they
are; the autosave metadata's project key names the snapshot's design
file, and the format "project" of save_design means version 3, a
design in a project.
- Feature:
FeatureUid(u64), stored asF<n>. Timeline order is a separate list; an index is not an id. - Sketch entity:
EntityUid(u32)within its sketch:c<n>curves,p<n>points,t<n>texts (one number space); constraints and dimensionsk<n>. - Body:
BodyUid= creating feature + ordinal (F7.b0). The display name (Body1) is separate. - Component / occurrence:
C<n>(rootC0) andO<n>; an occurrence is named<component>:<n>. - Parameter: referenced by a persistent
ParamId, so it can be renamed. A model parameter'sowneris the feature whose dimension it is and is deleted with it.
Document: parameters, timeline (Vec<FeatureUid>+ features), the timeline marker (roll-back point), components and occurrences, settings.- Tables (mitcad#667,
core/model/src/tables.rs, table-lookups.md): named tables of constant cells beside the parameters, which expressions read withTable.ColumnandXLOOKUP,MATCH,INDEX. The parameter table evaluates with the document's tables (TableSource); a table edit re-evaluates the parameters that use it in one atomic step, so features recompute only where a value changed. FeatureEntry { uid, name, suppressed, component, def: FeatureDef }. EachFeatureDefvariant has its own module incore/model/src/features/giving dependencies, validation and evaluation.- Body state: each feature maps the previous
BodyUid → Shapestate to a new one (New Body, Join, Cut, Intersect). A failed feature is skipped. State is per component; a feature sees only its component's bodies. - Recompute cache: keyed by the feature's definition, the values of
the parameters it uses and the versions of its inputs; reads of other
features' results are recorded in the key (
Read::Output,Read::Datum). A result's version is a 128-bit fingerprint of uid, definition and inputs (core/model-base/src/fingerprint.rs), stable across documents and processes. - Appending to a long timeline (mitcad#841): a command's recompute
goes on after the document's last results when the new state begins
with the same feature entries and nothing they read of the state
changed (parameter values, join tolerance, library sources, split
memory, the assembly; no joints): it takes their results as they are
and goes through only the features after them
(
recompute::recompute_after), with the result a recompute from the start gives. An importer's batches of features (FeatureBatch) thus cost what they add, not the timeline before them. Features are looked up by uid through an index (core/model/src/feature_index.rs) that checks every position it gives against the timeline, so it needs no upkeep when the timeline changes. - Result store (
core/model/src/store.rs): costly results are also kept on disk under the same key, so reopening a design or an older version reuses them. Shapes are stored with their face names and the edge and vertex names derived from them, which a shape read back takes instead of deriving them again (geometry/include/mitcad/geometry/persist.hpp); results of another build are ignored; sketches and construction features are not stored (base features are, also those that only bring in bodies: a stored body keeps the edge and vertex names that bringing it in derives, mitcad#887). An import's worker hands every result a store takes over to the window in a store of the import's own (mitcad#413). A result found keeps the shapes of the bodies it sets packed until something may read them (mitcad#858): the body states hold a stand-in under the stored version, an evaluation unpacks those it reads as it reads them (mitcad#886: the others stay packed), a joint unpacks them first, the bodies left at the end are unpacked, and a state the next restored result replaces is never unpacked (its result unpacks itself if the timeline's history is read later). What is unpacked together is unpacked on the machine's threads, a result's several shapes too (mitcad#887). The store also keeps the shown bodies' display triangulations under each body's version and the meshing options (see the display meshes below). The memory cache has a byte budget (the app gives a quarter of RAM) and evicts least recently used results not held by the current document. Thecachequery reports both caches. - Sheet material state:
sheet_rulespublishes resolved versioned fabrication rules;sheet_faceconstructs exact named planar material domains throughKernel::sheet_shape. A body shape and its sheet delta are applied atomically, with final component ownership and matching shape generation. Rule and sheet reads participate in cache keys, including missing inputs and failed-operation blockers. Arbitrary body replacements invalidate existing material semantics; rigid moves transform them. The result store persists paired shape/domain outputs under a sheet protocol version. Native files store definitions and settled panel provenance; Paste New copies external rule dependencies and their parameter closure.sheet_unfold/sheet_refold(andsheet_cutandsheet_corner_relief, which cut the developed material) develop and refold chosen bends by traversing the labelled panel/bend graph from a fixed panel in the model (core/model/src/sheet/folded/develop.rs); charts keep their material coordinates and only their embeddings change, so the kernel only reconstructs. A cut that disconnects the material publishes every piece as a body with its own sheet state (the first in geometric order keeps the id, the others are the cutting feature's bodies). A Flat Pattern is a document item (flat_patterns, saved in the design file), evaluated on demand at the marker from the body's sheet state with its own cache; it is never a body. Copies of components copy the items of their bodies, and design diffs list them. See sheet-metal.md. - Cancellation: a recompute reports progress to a
RecomputeMonitorand stops between features when cancelled. Commands, undo, redo and previews compute the new state before committing it, so a cancelled one changes nothing. Inside a feature, long OCCT operations (booleans, fillets, sweeps, lofts, offsets, splits, sewing) poll the monitor through a progress range (Kernel::interruptible,geometry/include/mitcad/geometry/cancel.hpp) and throwCancelled. OCCT's fillet and chamfer do not look at their progress range everywhere, so a call of theirs that does not return would hold the recompute and its Cancel for good: the OCCT kernel runs each fillet's and chamfer's call on a thread of its own (core/ffi/src/kernel/abandon.rs, mitcad#1917) while the evaluation's thread waits. So do the other calls seen to run on without returning (mitcad#1922): shells and offsets (Shell, Offset Face, Thicken, Offset Surface: OCCT's offset looks at the range only between its steps), sweeps (Sweep, Pipe, Coil, Helix, Loft, solid and surface: OCCT's pipe shell, pipe and loft ignore the range, our helical sweeps have none; a pipe along a tight helix ran for minutes, mitcad#1788) and healing (Delete Face's defeaturing, which ran 300 s in a fillet's retry, mitcad#1337, and the ShapeFix healing of a body built from its boundary, whose repair of intersecting wires once never returned, mitcad#495). It gives the call up within 10 ms of the monitor's cancel (the call fails as cancelled), or once the call has run for the kernel's time limit (300 s by default,MITCAD_KERNEL_TIME_LIMIT, 0 for none; on the wall clock): the feature then fails "the geometry kernel did not finish within N s; the operation was given up", and the recompute goes on. The call given up goes on on its thread with its geometry cancelled (OCCT's algorithms that look at a progress range stop there), sharing its input shapes as the import's parallel definitions do (#95), and drops its result when it returns; the process ends without its static destructors meanwhile (Hangs below). A monitor can be part of others (RecomputeMonitor::within): cancelled with any of them or at its deadline. The.f3dimport tries each definition under one, with the user's stop, the hang watchdog's give-up of the try, its memory guard and the item's time as its reasons to stop (#69, #71, #80), and the definition's share of that time, at which it gives way to the next ones and waits for what is left (#78). Without a monitor (mitcad-cli) nothing stops early. - Parallel evaluation:
Document::forkcopies a document for another thread (definition, cached results and last recompute shared; a kernel of its own fromKernel::fork, None where a kernel cannot work on another thread), andDocument::adopt_resultstakes a fork's results into the document's cache. The.f3dimport evaluates the definitions ranked after the one it tries on such forks, withthreadsworkers, and takes their results in rank order, so the import is the one of a single thread (#95,core/import/docs/f3d-performance.md, Definitions evaluated in parallel). Its kernels must beImportKernels:Send, with shapes that threads may share (Send + Sync). Within the samethreads(Progress::helper) the import reads the file's bodies on several threads, heals the large bodies of each history's first state, and of the first states the replay asks for, while the rest is read (#245, mitcad#676), and builds the history's bodies ahead of the replay (#103, Work beside the replay); the timeline items themselves are replayed one after another. EveryKernelisSendwithSend + Syncshapes, since forks go to other threads. - Components evaluated in parallel (mitcad#842,
core/model/src/recompute/ahead.rs): with recompute workers (Document::set_recompute_workers, 1 by default; the environment variableMITCAD_RECOMPUTE_WORKERS, which the ctestscore.model.<area>.workersset), the recompute cuts the timeline into windows that end at barriers: joints and the other features that move or make occurrences, sketches with driven dimensions and Bound Length (they write parameters), and features that change other components' bodies. In a window each component's features run ahead on a worker with a kernel of its own (Kernel::fork,Kernel::worker_thread); a feature that reads other components (links, or reads of their bodies, placements or results in its last result) is left to the recompute. The recompute itself goes through the timeline in order as with one thread and takes a worker's result only where it would take a cached one (the same definition, every recorded read holding where the recompute is, the definition's parameter values the same) and the evaluation succeeded; otherwise it evaluates the feature and cancels the rest of that worker's job. Results, versions, topological names, statuses, warnings, the memory cache and the monitor's progress are therefore those of one thread; a stop cancels every worker and keeps nothing they returned. Results not yet taken count against the memory cache's budget, and the workers are stopped (and waited for) before the cache drops results for its budget, since the cache keeps what a worker still holds. - Rolled-back features evaluated beside the document (mitcad#1267,
core/model/src/document/rolled_back.rs):Document::rolled_back_runforks the document with the marker at the end,RolledBackRun::runrecomputes the fork (on another thread; its monitor cancels it), andDocument::adopt_rolled_backtakes the results it evaluated into the cache when the document's definition is still the run's (the marker aside), the nearest the marker first and within the budget beside what the document's results hold (Cache::adopt_new,Cache::held_bytes); the next marker move then evaluates nothing. The application runs it at its idle points (Background evaluation under Application). - Memory: an allocation that fails ends the process (Rust's cannot be
caught; OCCT's
Standard_OutOfMemoryandstd::bad_allocinside a kernel operation become its error ": out of memory",KernelError::OUT_OF_MEMORY). The.f3dimport therefore measures the process against its tightest limit (core/ffi/src/memory.rs: an address-space or data limit, a Windows job's limit or the commit left, the memory the system has left) and gives up definitions before an allocation can fail (core/import/docs/f3d-performance.md, Memory). OCCT's own allocator throws instead of returning null (a patch of the port, #132) and counts its failures per process and per thread, the jobs of OCCT's thread pool counted for the thread that ran them (geometry::failed_allocations,failed_allocations_in_thread): OCCT's checker and healing catch failures inside and go on, so an operation, the checks and the build of a body from B-rep data compare their thread's count before and after and fail "out of memory" when it moved, and the import's memory guard takes a moved process count as low memory. - Hangs: a kernel call cannot be interrupted, so the
.f3dimport's watchdog gives up a try that makes no progress for its hang limit and runs the import again. The import ticks it between kernel calls, also in its own long loops (building and measuring a history state's bodies, finding faces and edges) and as OCCT's algorithms report progress (the healing of a body built from the file, and the interruptible ones above:CancelSource::progressed), so only a kernel call that does not return counts (#82). A try given up keeps its thread until the call returns; a process that ends meanwhile ends withstd::_Exitonce its output is written (abandoned_imports():mitcad-cli, the import worker, the application), as the shared libraries' static destructors would tear down OCCT's state under that thread. The kernel calls a Cancel or the time limit gave up (fillets, chamfers, shells, offsets, sweeps, healing) count there too (mitcad#1917, mitcad#1922, Cancellation above); with them, the import's try given up inside one of those calls returns at once. - Undo: the definition state (parameters, features, marker, body
attributes, assembly, visibility, named views, analyses) is cheap to
clone and pushed on a stack; several commands can merge into one step
(
merge_undo). Each state has a revision number, somark_savedand thedocumentquery'smodifiedwork without comparing files. - Parameters: name, expression (
d1 * 2 + 5 mm), unit, comment, kind (model or user), evaluated in dependency order; cycles and unit mismatches are errors. Internal units are mm and radians. Input accepts a decimal comma (core/expr/src/lib.rs); stored expressions always use points. The language is a superset of.f3dexpressions with the functions and syntax of spreadsheet formulas (mitcad#663): case-insensitive function names,=comparing inside parentheses,let,value(x; "mm");letnames areNodeKind::Local, never parameter references. Printed fit suggestions (print_fits.rs) are a table of ordinary user parameters, created only by explicit feature-field references during definition-state resolution. They share the feature's transaction and undo step. The UI reads their names from the model; expression hints and generator reports evaluate prospective defaults on parameter copies, while previews use the usual private definition-state copy. Limits (mitcad#665,core/expr/src/limits.rs): a parameter's optionalmin,max(expressions that join the dependency graph) andstepclamp and snap its value, or refuse it whenstrict; the table keeps the result before them and which limit took effect. Text parameters (mitcad#664): the unitUnit::TEXT(Text) gives a parameter a text instead of a number. An expression's value isexpr::Value(aQuantityor a text); the evaluator's numeric path refuses a text and the text path a number, so the two never mix.Lookup::lookup_textgives text parameters to expressions. A sketch text follows one through the sketch'stext_values(slottexts[t5].text, aParamIdlike any slot, so renames, ownership and dependencies are the usual ones); the recompute records a text parameter's read as a hash of its text (Parameters::read_bits). - Construction geometry: planes, axes and points are features that
make a datum, not bodies. Features refer to geometry through
GeomRef(origin datum, construction feature, or a body face/edge/vertex) and to paths throughPathRef. - Body attributes (visibility, material, appearance; steel by default) live in the definition state.
- Materials (mitcad#640,
core/model/src/material.rs,document/materials.rs): objects with a density, an appearance and an optional filament (Print Filamentvalues),based_on, a version and an origin. The built-in ones keep the old ids (steel,pla, ...); a design keeps materials of its own in the definition state and the design file (one with a built-in's id takes its place), and default materials of components. A body is made of its own material, else the nearest component's default up the occurrence path, else the root's, else steel. Setting a body's material sets its appearance too, unless the body's was set by hand. - Material properties (mitcad#1213): a material's optional
mechanical and thermal values (
MaterialProperties, in MPa, °C and µm/(m·°C)) and itsreference; data only, no analysis uses them.material_units.rsconverts the model's units into a design's system (its length unit's: metric or inch) and the temperature unit the application passes, as scale and offset, which the application applies (material_unitsquery).material_exchange.rswrites and reads materials as JSON and CSV that state their units (material-files.md), each row checked on its own;document/material_import.rsimports into the design or a library as one undo step. The bundled material dataset (material_dataset.rs, third-party data under Apache-2.0 inthird_party/material-properties, and MitCad's own woods and panels of the class Wood, mitcad#1552, incore/model/data/wood_materials.json) is compiled in and read through the same import; a material made from it is the user's own copy that remembers the entry. - Print settings key map (mitcad#640,
core/print-keys): one Rust table of MitCad's printer, process and filament keys, each with its type, unit, choices, plain name and, per slicer dialect (the Bambu Studio family, PrusaSlicer, Cura), the slicer's key and the conversion of values; built from the slicers' option definitions by meaning (the module documentation names them). Export and import of print settings convert through it. Each key also has its place in the settings form (mitcad#655: a category, a group, advanced or common), in the table's display order, so the application keeps no list of its own. - Print profiles (mitcad#640,
core/model/src/print_profile.rs,document/print_settings.rs): the design keeps printer and process profiles in its definition state and file; components, occurrences and bodies choose one and override values in thePrint PrinterandPrint Processproperty sets, typed by the key map. What a body prints with is resolved root, components down the occurrence path, occurrence, body (nearest wins; a level's own values before its profile's), with the material's filament (print_settings,build_volume). - Print libraries (
core/model/src/print_library.rs,document/print_library.rs): materials and profiles are JSON items of the base library (the component library's manifest lists them; read through the library resolver,LinkResolver::print_library), the user's folder and the project's folder; the design keeps complete copies with their origin and takes a newer version only on request.document/library_items.rs(mitcad#655) lists the choosable items where they live (library_items: built-in, base, user, project, the design's own), edits an item in its library file with the design's copy taking the same change in one undo step, and copies a library's item in within the undo step that chooses it. - Slicers' files (
core/model/src/print_files/,core/3mf): the import reads a slicer's settings (Bambu Studio family JSON, PrusaSlicer INI, Cura stacks; presets and bundles) into profiles and materials, never geometry; the 3MF export writes each body's effective settings in a slicer's dialect (core/3mfcarries more metadata, per-object metadata and files;read_packagereads them without the geometry, within a budget checked against the declared sizes before reading: at most 4096 entries and a 256 MiB model part, other files over 64 MiB left out and 256 MiB for the files read in all, mitcad#927). - Filament changes at print heights (mitcad#1596,
core/model/src/print_changes.rs,document/filament_changes.rs,print_files/layer_events.rs): a schedule of heights and what happens there on a single extruder (a manual change to a filament, a material with its appearance; or a pause), kept in the design file (filament_changes) and set as one undo step (set_filament_changes). The design's geometry is never cut or changed for it. Decisions:- Scope: a plate, never a body. A manual change swaps the one filament loaded, so it changes the whole layer of every object on the plate. The design's own schedule is that of an export of bodies and of every print plate without its own; a print plate may have its own, which goes with it when it is deleted. Below the first event every part on the plate must print with one filament (material and appearance): parts of several filaments on a plate are a conflict, a warning of the export, and none of that plate's events is written. Several filaments at once are a multi-material print, which the filament slots already write.
- Coordinates. Heights are millimetres above the print bed, whatever
the design's unit: the bed's Z after the export's turn (a print bed
face, the automatic orientation) and drop. In a 3MF each build object
is measured from its own lowest point (where the slicer lays it); a
plate's top is its tallest object's.
model_renderand USDZ measure each placement along its print direction (away from its print bed face, else +Z) from its own lowest point. - Layers. An event happens at a layer boundary: its height moves to
the nearest top of a layer (
first_layer_height, thenlayer_heightof the plate's process, 0.2 mm each when unset; a tie upwards), never within the first layer, which always prints the plate's own filament. It is written at the top of the first layer printed after it, which every supported slicer assigns to that very layer. An event at or above the plate's top, the earlier of two events on one boundary, and a change to a material the design no longer has are left out with a warning. Heights are above 0 and at most 2000 mm, one event per height, at most 64 events; variable layer heights are the slicer's. - Filaments and dialects; no printer G-code in the model. The design
keeps the material and appearance; each slicer gets its own per-layer
event file, and emits its printer profile's own change or pause
G-code. PrusaSlicer (read from its release 2.9.7,
src/libslic3r/Format/3mf.cpp:CUSTOM_GCODE_PER_PRINT_Z_FILE,_add_custom_gcode_per_print_z_file_to_archive,_extract_custom_gcode_per_print_z_from_archive;src/libslic3r/CustomGCode.hpp:TypeColorChange 0, PausePrint 1;GCode/ToolOrdering.cppassign_custom_gcodes, which gives an event the lowest layer whoseprint_zis at or above it, andGCode.cpp, which emits a colour change of a single extruder only forextruder >= 1) getsMetadata/Prusa_Slicer_custom_gcode_per_print_z.xml: acustom_gcodes_per_print_zelement per bed (bed_idx, bed 0 always), acodeper event (print_z,type,extruder,color,extra, the pause's message) and themode(SingleExtruderfor a project of one filament;MultiExtruder, orMultiAsSinglewithsingle_extruder_multi_material, for more, which PrusaSlicer compares with its printer before taking a change). A change is a colour change (M600) of the plate's extruder: the filament's settings stay the first one's, a warning when the two differ in type or temperatures. The Bambu family (Bambu Studio release v02.09.01.70, OrcaSlicer v2.5.0 and QIDI Studio:bbs_3mf.cpp/qds_3mf.cpp,_add_custom_gcode_per_print_z_file_to_archiveand_extract_custom_gcode_per_print_z_from_archive) getsMetadata/custom_gcode_per_layer.xml:custom_gcodes_per_layer, aplateper plate (plate_info idfrom 1), alayerper event (top_z,type,extruderfrom 1,color,extra) and themode. Their G-code export leaves a colour change (type 0) out (GCode.cpp, "inserting color gcode is removed"), so a change is a filament change (type 2, ToolChange) to the filament's own slot inMultiAsSinglemode, the slot the export adds for each filament changed to; theirassign_custom_gcodestakes the nearest layer, which atop_zat a layer's own top is. No printer G-code is written (the readers take the legacygcodeattribute only withouttype). When every plate's parts print with one filament, the slot a change adds is only the manual change's, and the project'senable_prime_toweris written off: the slicers would otherwise build a tower at their defaultwipe_tower_x/wipe_tower_y, which fell outside a 256 mm bed in real runs (Bambu Studio and QIDI Studio stop with -104), and a manual change purges in the printer's own filament-change code. Every family export also keeps relative extrusion valid: withuse_relative_e_distanceson (their default) and noG92 E0line in the layer change G-code,G92 E0is added tobefore_layer_change_gcode(OrcaSlicer refuses the project otherwise). The slicers count filaments byfilament_diameter(OrcaSlicer'sToolOrdering), and with one entry a change becomes a colour change, whose G-code their export leaves out: a project of several slots always has an entry per slot. For a manual change on a printer withoutchange_filament_gcode, the export writes M600 there, guarded byprevious_extruderso that the print's first filament does not stop. A slicer's 3MF not put on the bed (on_bed) is centred on the plate as a whole (center), as the slicers take a project's positions as bed coordinates. Cura keeps such events only as post-processing scripts of the machine's settings, not in what its 3MF export writes per object: the export warns with each event's layer number to add there. A 3MF without a slicer warns that the events go with one. Object height ranges (per-object layer settings) are not filament changes and are not used for them. - Preview.
model_render'sprint_colorsand the USDZ export'sprint_colors(opt in) cut the drawn or written triangles at the boundaries of the changes (print_changes::band_mesh: a triangle across a cut becomes a convex piece per band, new vertices on the cut, normals interpolated) and colour each band with its filament's colour, in place of the face appearances, which stay the design's for every other picture and file. Both take the same placement's schedule, layers and direction (Document::print_colors), so they agree; USDZ writes the first band as the mesh's material and each other band as a subset. Pauses change no colour. - At planes and faces (mitcad#1643). An event's place is a height or
a reference (
at: a construction or origin plane, a planar face) by the model's usual references, so it follows edits; its height is worked out each time it is needed, never stored: along the print direction from the lowest point of the body it is measured from (the face's own, the one named, else the plate's first) to the plane. The export measures in the 3MF's own placements (the turn onto the bed applied, each object from its own lowest point), the query and the print colours in the design's placement of the body; a plane not level in that orientation, gone, or of another component gives no height and the event is left out with a warning in words, never moved. Objects of one plate that stood at other levels in the design are said once per plate, as the conflicts are. The app's Send to Slicer edits the schedule in its Filament changes section and draws the bands and rings over the view fromfilament_change_preview.
- Appearances (#46,
core/model-base/src/appearance.rs): physically based parameter sets (base colour, metalness, roughness, specular, transmission, IOR, coat, emission, opacity, and a texture for the base colour: an image file or one embedded in the design file, #53, with normal, roughness, metalness and occlusion maps and the set's source, #313; an embedded image is kept once per design by its SHA-256, shared in memory and in the file), and a class, the materials' (core/model-base/src/material_class.rs, mitcad#1102: Metal, General Plastic, FDM Plastic, Resin, Wood (mitcad#1552), Other; a library appearance's from its id, never written), by which the pickers offer a material's class first. The library is built into the model; a document's own appearances are in the definition state and the design file, changed by undoable commands that recompute nothing. Bodies refer to one by id, and so do single faces by topological name (a body attribute; the face's appearance overrides the body's and follows the face as other face references do). The shaded view uses the display colour (the base colour) of bodies and faces, the rendered view every parameter and the texture with all its maps (#314). View > Component Colors temporarily overrides body and face colours in the shaded and wireframe views with a stable colour per owning component (shared by its occurrences). This user preference does not change appearances, exports or the document. Enabling it leaves the rendered view; entering the rendered view turns component colours off. - Render settings (#47,
core/model-base/src/render_settings.rs): how the rendered view lights and shows the design, per document: the environment (a built-in studio or outdoor setup, or an HDR image), the background, the ground and the film (exposure, view transform), and the final render's output (#48: size, samples, time limit, denoising, transparency, file format), as sections of fields with defaults, so that more sections can be added and older files open; and the user's lights (#54: point, spot, area and sun lights, placed in the design or relative to the camera), a list changed by commands of their own and compared light by light. They are in the definition state and the design file (left out while they are the defaults), changed by undoable commands that recompute nothing, and compared field by field in the comparison of versions. - Analyses (
core/model/src/document/analyses.rs): section analyses kept in the definition state with a name, a plane reference, an offset, a flip and a light bulb; their commands are undo steps that recompute nothing. The plane is resolved at the marker when asked for (theanalysesquery), so a face's section follows the model by its name. One is shown at a time, so one plane cuts the bodies; the app cuts the view where the shown one says (MainWindow::followAnalyses), except while Section Analysis' panel previews its own. Print analyses (mitcad#620) are kept the same way with their bodies, a bed face and their settings; their overhangs, thin walls and estimate are worked out in Rust (core/model/src/print_analysis.rs, theprint_*queries) on the bodies'Kernel::triangle_meshandphysical_properties, with a bounding volume hierarchy of their own for the wall rays, no kernel method of their own; the results are kept in memory by the bodies' shape versions and the settings. Their narrow gaps between bodies printed in place (mitcad#1519,print_min_gap) are a box test in Rust and the kernel's exactmeasure_betweenfor the pairs left; for bodies that touch, the kernel'sface_separations(the faces within the gap, pair by pair, with their normals, mitcad#1672) and Rust's choice of the faces that face each other across air. - Image references (mitcad#782;
core/model/src/document/image_references.rs,core/model-base/src/image_header.rs,api/image_references.rs): pictures kept in the definition state with a name, a plane reference resolved at the marker as an analysis' is, a centre, angle and flip in the plane's frame, the size of a pixel, an opacity, a light bulb and the image file's bytes (anImageData, saved base64 in the design file). The model reads only the files' headers (size and resolution; a HEIF file's size as shown, after its rotation and crop, mitcad#850); the app decodes the pictures (view/ImageFile.*: Qt's readers, HEIF through the operating system's decoder,view/HeifDecoder.*behindplatform/PlatformHeif.hpp: ImageIO on macOS, WIC on Windows, the distribution's libheif loaded at run time on Linux, looked for only when a HEIF file is decoded, mitcad#1304; libheif and libde265 from vcpkg instead in builds withMITCAD_HEIF), embeds a HEIF file it inserts as a PNG file of the upright image, and draws them as textured quads by the corners theimage_referencesquery gives (MainWindowImageReferences.cpp,view/ImageReferenceView.cpp). Their commands are undo steps that recompute nothing. - Annotations (mitcad#702, grown from the measurement objects of
mitcad#649;
core/model/src/document/annotations.rs,api/measurements.rs,api/annotations.rs,iso286.rs): dimensions, leader notes, datum labels and feature control frames kept in the definition state with a name, a colour, a light bulb, a group, a kind (distance, angle, offset, axis or centre distance, radius, diameter; the leaders note, datum and frame: a letter, an ISO 1101 tolerance whose rules Rust checks, a frame under a dimension), one or two picks as themeasurequery's selections (topological names with their occurrences), the plane they lie in (a direction or a picked plane), the dimension line's and the text's places relative to the picks, a format and a tolerance (ISO 286 fit codes computed in Rust); their commands are undo steps that recompute nothing. Each is measured at the marker whenever theannotationsquery asks (the kernel's measures andapi::measure_axes), and laid out in Rust in its plane: extension and dimension lines, arcs, arrows, the text's place and direction, the value in words ISO 129 style; a pick that is gone gives an error instead, and the annotation stays. Since mitcad#894 the texts' height is the design's, in millimetres (set, or Auto from the ISO 3098 series by the size of what is annotated), a new annotation's colour isauto(the background tone's annotation colour; the old rotating defaults read as Auto), and a length's automatic dimension line lies outside its bodies' extent in its plane, stacked outside parallel lines, all worked out in Rust from the picks' bodies' boxes and planar faces kept with the measured picks. The app projects the layout, keeps the text readable within its plane (ISO 129-1), sizes the text and arrowheads by the model's height on screen and paints it with QPainter (app/view/MeasurementDrawing,MeasurementOverlay, which also takes clicks and drags on the texts and lines), in snapshots rendered offscreen at a larger size (OcctViewer::snapshot, OCCT'sV3d_View::ToPixMap; all, or one group) and over Render Image's image; the Annotations window lists and edits them (app/view/AnnotationsWindow). Since mitcad#902 hole callouts (api/hole_callouts.rs) are annotations whose text the model writes from the hole's feature with the exported drawing's engine (compose::hole_callout, in ISO 129-1's symbols); leaders report which end of their text the leader meets and end in a dot on a face; a plane's extension line starts at the picked face's own outline (MeasuredPicks::outlines); default places are in text heights. The app paints the reference look: the bundled technical lettering (an ISO 3098 type B style font, a file loaded at run time, LGPL-3.0 with the font exception), crisp lines on the pixel grid, arrowheads in the annotation's plane, the text to the design's scale above a floor on screen (no ceiling since mitcad#1168; a leader's landing in proportion to its text as drawn), selection and hover as a recolouring only, Auto's ink chosen over what lies behind (the view's frame grabbed once the camera rests,MeasurementBackdrop; lines and terminators piece by piece, text and frames one ink each; no casing or halo), and pictures in the tone of their own background. Since mitcad#1097add_annotationwith"preview": truereturns the annotation as theannotationsquery will list it once added, laid out after the others by the same code (Document::annotation_to_add,laid_outwith the annotation to add), and stores nothing; the Make tab's Annotate panels draw it dimmed before Add (CommandDef::acceptPreview,OcctViewer::setMeasurementPreview). - Drawings in the design (mitcad#707,
core/model/src/drawing/def.rs,document/drawings.rs,api/drawings.rs): drawings kept in the definition state in the root's and components' Drawings folders, each sheets of views (base, projected, section, detail; breaks on any) with their places, scales, styles and subjects, and nothing computed. Their commands are undo steps that recompute nothing; the design file and the comparison of versions keep and list them; a component's drawings are copied with it (DocState::copy_drawingsincopy_component_mapped) and go with it. Thedrawingquery works a sheet out at the marker: each base view's subject in the drawing's component's coordinates, projected byKernel::project_view(no kernel method of their own) and kept in the document's projection cache (mitcad_model_drawing::ProjectionCache, by shape versions, placements and the view's spec); details and breaks are cut in Rust in the view's plane (core/model-drawing/src/clip.rs), shaded views fromKernel::triangle_mesh; threads are drawn by ISO 6410 before that and details smaller than the pen simplified when the view is drawn (core/model-drawing/src/convention.rs, mitcad#1112); the sheet is drawn by the export'scompose::render(core/model-drawing). A view's place is where the component's origin lies on the sheet, so views in line share a coordinate. The application paints the query's groups with the query's pens (the writers' line widths) in a sheet view of its own (app/COMMANDS.md, "Drawings"). Annotations on views (phase 2, stored incore/model/src/drawing/annotate_def.rs, laid out bycore/model-drawing/src/annotate.rs,api/drawing_annotations.rs) keep picks of model topology (a body, its occurrence, an edge or a round face by its topological name): a click is matched in Rust against the bodies' named edges and faces as the view projects them (Kernel::edge_geometries,Kernel::face_geometries, kept per shape version in the same cache), and each pick is found again by its name whenever the sheet is drawn, so the annotation follows the model or is marked broken. Their values are written by the model annotations' engine (api/annotations.rs, mitcad#702) and laid out on the sheet in paper millimetres relative to their picks. A view sees what it shows (mitcad#717): a section what lies behind its plane, and the planar faces its plane cuts (their cut edges, matched in Rust against the projection's cut faces); a detail and a broken view the parts of edges they show; of picks as near, the one the projection draws visible, then the one nearest the eye; a pictorial view measures aligned dimensions in 3D and refuses foreshortened ones. The silhouettes of curved faces (mitcad#1909,Kernel::face_silhouettes, kept per body version and view direction,api/drawing_silhouettes.rs) are picks too, kept as the face and a point of the outline in its body's coordinates, found again as the face's outline nearest that point; a pick'sextremedirection makes it the point of its curve furthest that way, so an overall size to the top of a curved outline follows the model. A view may also bring in the model's own annotations it sees square on (mitcad#1406,model_annotations): the model lays them out (api/annotations.rs,model_items), and the view draws each, once per sheet, as an annotation of the drawing's engine made from the model's measured points and words, not stored; one kept as the drawing's own becomes a stored annotation with picks of its own (kept_from). Tables (phase 3,drawing/tables_def.rs,core/model-drawing/src/tables.rs,api/drawing_tables.rs) are annotations of a view too: a hole table (Kernel::round_holesof the bodies it shows, seen end on) and a parts list (the view's occurrences counted per component, theparts_listrows' and properties' words) are worked out whenever the sheet is drawn and drawn in Rust; balloons take their numbers from the sheet's parts lists. Sheet templates (phase 4,drawing/template_def.rs,core/model-drawing/src/template.rs,api/drawing_templates.rs) are data: a frame, a title block's lines and fields with names in braces, a revision table; built in (JSON files compiled in), or files in the user's and the project's library folders (beside the materials and print profiles), read and written by the model; a sheet keeps a copy of its template, and its fields are filled in from the design (properties, materials, the mass from the bodies' volumes) whenever it is drawn. A drawing's revisions are rows of the drawing itself. A cut sheet (mitcad#853,drawing/cut_sheet_def.rs,core/model-drawing/src/cut_sheet.rs,api/cut_sheets.rs) is a drawing of its own kind: its parts are bodies seen along a planar face's normal at 1:1, their outlines the bodies' silhouettes worked out in Rust from the kernel's hidden-line projection (the regions it bounds classified by segment crossings through the body), written as DXF and SVG for cutting; B-spline edges come through the projection as B-splines (ViewCurve::Spline) and are written as the curves they are (core/model-drawing/src/bspline.rs). - Parameters as CSV (mitcad#666,
core/model/src/parameters_csv.rs,document/parameters_csv.rs,api/parameters_csv.rs): MitCad's parameter table and the.f3dapplication's parameter table CSV are read and written in Rust; the queries and the command carry the CSV text, and the app only reads and writes the file (Edit Parameters' Import and Export). An import works on a copy of the definition state row by row in dependency order, as the.f3dimport does, and is one undo step; its preview runs the same rows on a copy that is dropped. - Components (
core/model/src/assembly.rs): structure is in the definition state, not on the timeline, though features can create components. Occurrences belong to a component, so sub-assemblies are shared and world placements are paths from the root. One timeline; occurrence moves on it are placement changes. A feature refers only to geometry of its own component, except joints (below) and a sketch's plane and projections, which may name another component's geometry through anOccurrenceLink(#100,core/model/src/links.rs): the occurrence paths from the root to both components, resolved at the sketch's point of the timeline (placement(target)⁻¹ · placement(source); the cache keys on those placements and the other component's bodies,Read::Placement,Read::BodyIn). The.f3dimport makes them for sketches on other components' faces and for linked sketch curves that follow one edge of the replay (#225,core/import-replay/src/linked.rs). A linked external component is read-only; its bodies are stored in a base feature refreshed on open. Since a feature's component is only itsFeatureEntry::component, features made in the root can later move into a new component placed at the identity (#171,document/move_features.rs): their uids and topological names stay, the occurrence paths that reach their geometry (links, joint origins) take the new occurrence, and which features must go together follows from what the last recompute read and changed. Bodies alone move into an existing component at a point of the timeline by abody_transferfeature of the destination (mitcad#465,features/body_transfer.rs): the same body ids, converted once into the destination's coordinates (by the placements there along anOccurrenceLink, or a fixed rigid transform an import keeps), owned by the destination from then on (FeatureOutput::owners). - Joints (#55,
core/model/src/joints.rs, phases 1 to 3): timeline features of a component (joint,as_built_joint,joint_origin,rigid_group) that connect its occurrences. The one cross-component reference: a joint origin is an occurrence path from the joint's component plus aGeomRefresolved in the component that path ends in (that component's bodies, sketches and construction geometry at that point of the timeline) and moved into the joint's component by the path's placements. A joint's evaluation only reads its values (cached); recompute then applies it after the cache, likeplaceapplies placement changes, because it reads other components' bodies and the placements so far: it resolves its frames and the joint solver (mitcad_solver::RigidSystem,core/solver/src/rigid.rs, on the sketch solver's iteration, factorization and rank analysis) solves it with the joints before it that share moving occurrences, a body per unit (an occurrence with what its rigid groups join to it; grounded ones fixed), moving them as little as possible. The units that moved getPlacementChange::Sets of the joint feature; the occurrences' stored transforms stay the starting placements. Contradicting joints fail the feature. Motions are driven by a stored position (else the rest value) or free within limits; degrees of freedom are the rank of the joint equations; a drag query and command move occurrences while the joints hold. A joint moves only top-level occurrences of its component (a sub-assembly as a whole), except inside a flexible occurrence (mitcad#1793): its component's joints, constraint rows and links are brought into the parent's solve for it alone (paths through it, its own values;ActiveJoint::under), the occurrences they move inside it are units of their own, and their placements for that occurrence are kept apart from the shared ones (JointsState::flexed, read bypath_placement, the instances and the drags). Flexible occurrences nest (mitcad#1805): what one brings into its parent is brought on into the parents of that parent's flexible occurrences, under the chain of them (ActiveJoint::underand theflexedkeys are chains), and linked geometry reads those placements as recorded reads (Read::Flexed). Commands and queries: commands.md ("Joints"). In the application (phase 3) the ASSEMBLE group's panels add and edit them, a preview reports the placements it changes so that panels show the moved bodies, components are dragged in the view through the drag query, and joints are animated as previews of driven positions (app/COMMANDS.md, "Joints"). The.f3dimport (phase 4,core/import-joints/src/joints.rs) maps the file's joints to these features (Imports with history below). - Assembly constraints (#148,
core/model/src/constraints.rs,features/constraint_set.rs): aconstraint_setfeature's rows (align, angle, center, tangent, insert, axis insert) each hold geometry of one occurrence against another's, referenced as joint origins, with only some of a joint's equations (mitcad_solver::RigidConstraint, partial equations in frame b's coordinates, optionally with a value between limits). Recompute treats the rows like joints (joints::apply): they areActiveJoints with their parts, solved in the same runs, rank analysis, degrees of freedom and drags; conflicts name rows (Constraint1 row 2 (insert)). The application's Constraint command edits the rows in one panel, the type inferred from the picks by theconstraint_rowquery (commands.md, "Assembly constraints"). - Motion studies and contact sets (mitcad#454,
core/model/src/motion.rs,contact.rs,document/motion.rs): definition state beside the timeline, saved in the design file. A study keys joints' free motions along steps; a contact set names occurrences whose bodies stop each other. Motions that should stop at contact (Drive Joint, drags,play_studyand the previews of a study's playback and of Animate Joint's frames) are sampled from where they start, each sample the state with the joints driven there and recomputed (sweep_joints; a drag runs the joint solver's drag instead), checked pair by pair (boxes first, thenKernel::overlap_volumes, OCCT's fuzzy boolean common of the placed bodies,geometry/src/motion_contact.cpp), and the step before the first contact bisected; recompute itself never checks contact. The application plays a study in a panel of previews (app/motion/MotionStudyDialog), the document unchanged until Keep (commands.md, "Motion studies and contact sets"). The.solidcraftimport maps the file's onto them. - Motion links (mitcad#466,
features/motion_link.rs,core/model/src/motion_links.rs):motion_linktimeline features that make one joint's free motion follow another's: a ratio, gears, a rack and pinion, a screw (sizes as values or radii of picked round geometry, found again on every recompute) or a cam (a table of the follower's values over a turn, worked out from the profile, the follower and its tip; the contact geometry adapted from SolidCraft,third_party/solidcraft/cam.rs). Recompute applies a link like a joint (joints::apply): its joints and every joint, constraint and link sharing moving occurrences with them are solved together, the joint solver holding one coupling row per link (mitcad_solver::RigidCoupling, linear or a periodic table); the rank, drags and the contact-stopped motions of motion studies take the links in, so linked joints move together. A follower whose driver is driven lets go of its own position; Drive Joint and studies take the positions of linked motions away, so the last driven one drives (commands.md, "Motion links"). The application adds them with ASSEMBLE › Motion Link and lists them in each component's Motion Links folder; the.solidcraftimport maps the file's. - Design policy (#220,
core/model/src/policy.rs,document/policy.rs): the root and each component have nine local settings (sketches, features, components; sketch attachment to and from other components, and of a component's first sketch, #293; references to and from them), in the definition state and the design file. The general defaults (the Hybrid preset, mitcad#421) allow everything; the Part and Assembly presets are the stricter choices. A new design (Document::new_design) has the root and an empty, active Component1 (named as any new component, mitcad#711), both with the general defaults, as haveDocument::new, new components and owners without a stored policy (a stored one keeps its values; the file format is unchanged). Every change a JSON command or preview makes goes through one check before it is computed (apply_with,apply_move, previews): the next state's violations are compared with the current ones, counted per owner, setting, object and other owner, and a change that adds one is refused with the reason. Existing violations stay and are reported (thepolicyquery); a policy change modifies no content. Importers that call the model directly are not checked. Later move and reparent operations get the check by building their next state throughapply/apply_move(commands.md, "Design policy"). The one redirection: a new component (New Component, a feature's new-component operation) that an owner's policy refuses is placed in the nearest owner above that takes components, at the same place, and the reply says so (Document::component_parent_beside, #292). - Plastic part features (mitcad#459,
core/model/src/features/plastic.rs): Boss, Snap Fit and Rest are built in the model from the kernel's extrusions, booleans and fillets; Lip and Groove from the band along a rim face's loop (Kernel::rim_band,geometry/src/plastic.cpp). A plastic rule is a timeline feature that changes no body; the features that name it read its parameters and its result (Read::Output), so an edit of the rule computes them again (commands.md, "Plastic part features"). - Gears (mitcad#472,
core/model/src/features/gear.rs): the teeth are worked out in the model (gear_profile.rs: involute flanks fitted as B-splines, the generating rack's root fillet and undercut, ring spaces, racks, Tredgold bevel sections) and handed to the kernel as loops of named curves:Kernel::gear_sweepsweeps them straight (a prism) or along a screw motion in steps (helical, herringbone; faces built from each curve's poles moved along the motion and sewn,geometry/src/gear.cpp),Kernel::gear_conerules a bevel gear's section to its apex within its blank of revolution. Bores, hubs and grooves are further sweeps joined or cut. A gear meshed with another reads that gear's definition and parameters (and its result,Read::Output) to place itself; its result keeps its frame as the mountgear, whichlink_gearsreads to couple the gears' joints with a motion link (commands.md, "Gears"). - Pulleys (mitcad#562,
core/model/src/features/pulley.rs): the grooves of the timing belt profiles are worked out in the model (pulley_profile.rs: lines and arcs of a fixed groove per profile) and swept byKernel::gear_sweepas a gear's teeth are; flanges, hub, bore and set screws are further sweeps joined or cut. A pulley withbelt_withreads the other pulley's definition and parameters (and its result,Read::Output) to place itself; the belt's length is a derived value of thepulley_valuesquery. Its result keeps its frame as the mountbore(commands.md, "Pulleys"). - Printable bearings (mitcad#577,
core/model/src/features/printable_bearing.rs): no kernel method of their own. The model works out the bearing's section (one function of the distance from the pitch circle bounds both races, so they mirror each other), builds the races and the first element as regions in code revolved byKernel::revolve(an airsoft ball a sphere ofKernel::primitive), places the other elements bytransform_shapewith instance names, and cuts the cage's pockets and a raceway in a picked body with booleans. The printability checks are part of the section's layout, so the panel'sbearing_valuesand the evaluation give the same errors. A feature may name the component its new-component operation makes (FeatureInfo::component_name, used by the document when it makes the component); an airsoft bearing's balls are purchased rows ofparts_list(api/bearings.rs), not components (commands.md, "Printable bearings"). The seat on a shaft or in a hole is the shared seat resolver's (mitcad#578). - Seats on shafts (mitcad#578,
core/model/src/features/seat.rs): a pulley, a gear with a bore and the printable bearing take aseatinstead of a plane: one resolver turns a circular edge or a cylindrical face (Kernel::edge_geometry,Kernel::face_cylinder; another component's body read in its component and moved by the seat's occurrence link, as a sweep'sbody_links) into the end measured from, the axis and the diameter, which the part's frame and its plain bore follow. The app's panels place a part on a shaft through Place On (app/commands/PlaceInputs.hpp, mitcad#656):at.axisresolved as a seat,seatwith its link for another component's shaft. - Placement by picked geometry (mitcad#656,
core/model/src/features/place_at.rs): pulleys, gears, bearings, coils, primitives and holes takeat, one placement of three forms (on an axis: a seat, or an axis of its own; at a point with its sketch's or a plane's normal; on a face at offsets from two edges), kept as references and resolved into a frame by one resolver at each recompute, so the part follows what it was placed by. A gear placed so and meshed is only turned by its mesh.features/drives.rsworks out Gear Pair (modules and tooth counts that fit two axes: exact, by profile shifts, by a helix angle) and Belt Drive (tooth counts, catalogue belts and their tension travel);api/drives.rsserves them as queries and makes both parts in one undo step. The app's shared input isapp/commands/PlaceInputs.hpp; Gear Pair and Belt Drive areapp/commands/DriveCommands.cpp. The panels show distances as dimensions in the view, a value box on each handle (Manipulator::valueBox). - Extrude's automatic operation (#289, mitcad#575,
core/model/src/document/auto_operation.rs): a preview asked for it evaluates the extrusion as a new body, tries its tool against the visible bodies of its owning component (boxes first, thenKernel::tool_contacts, Join's contact test) and reports Join, Cut or New Body with the bodies. Added previews consider bodies at the marker; edited previews compute a temporary state strictly before the edited feature, excluding its result and all later geometry regardless of the marker. The report and retained geometry remain the supplied definition's ordinary preview, including any Cut scope, without changing the document or its undo history. The app decides when to take the answer into the panel (commands.md, "Extrude's automatic operation"). Contact preparation (mitcad#638) retains geometry-only face bounds, edge counts and eligible planes on the immutableShape, keyed also by contact tolerance. A changed BRep, orientation or location has a fresh index; display mesh quality does not affect it. Each query still evaluates its current tool and the model's current visible participants; no distance, operation or participant answer is retained. For planar faces with many edges, up to four tool vertices can prove contact using plane distance and OCCT's trimmed-face classification. A point in a hole, on a trim boundary or away from that plane uses the existing checks. - Extrude target conversion (mitcad#570): only Cut activates its
cut_scope; other solid operations may retain that scope as dormant editor data, with no geometry or dependency effect. A new boss storesinitialize_on_cut: truein that scope to distinguish automatic Join participants from explicit local body choices. Its editor initializes targets and snapshots visibility when the user chooses Cut. Previously chosen scopes retain exclusions through operation changes and file round trips. Legacy Cuts and explicit local participants remain local; opening an editor never expands targets. - Extrude of a body face (mitcad#535,
features/extrude.rs): an extrusion's profile may be a planar face of a body (profile_face) instead of sketch regions: the face is found by its topological name on every recompute andKernel::extrude_facesweeps a copy of it, holes kept, along its outward normal (geometry/src/face_extrude.cpp); the side faces are named after the face's edges, the caps after the face (commands.md, "extrude"). A revolution takes one the same way (mitcad#539,features/revolve.rs,Kernel::revolve_face,geometry/src/face_revolve.cpp; the FreeCAD import's face profiles), by angles only. - Press Pull continued (mitcad#1850,
features/press_pull.rs): Press Pull on a face makesoffset_face(Offset) orpress_pull(Straight, Along the walls):Kernel::press_pullbuilds the new piece from the face as an extrusion or a revolution of a body face does (geometry/src/press_pull.cppcallsextrude_faceandrevolve_face, so a Draft taper goes through Extrude's own taper path) and joins it to the body or cuts it; the walls beside the face decide Along's run (Kernel::face_run, theface_runquery: one axis of revolution or one direction), and a Scale taper or a taper along a turn is a loft or a sweep between the face and its end section. The moved end keeps the face's names. - BUILD (#375,
core/model/src/build/for what the design file keeps, the planning in the cratecore/model-build/): the library components the BUILD tab places are kept once as the design's library sources (library_sources: the library record, the design's text, inside a single file or in a project's store, and the manifest'sbuildblock). A placed part is a component whose first body is aderived_part(features/derived_part.rs): the source's design evaluated inside the feature with its row and values (a recompute of its own, with the document's kernel), its visible bodies copied and renamed<F>:part(<source face>)(Kernel::rename_faces), its ends cut at their long points (the plane through the section's outer edge on the long side: the length is the outer length) by booleans with a box (<F>:end_a,<F>:end_b), and itsmount:<name>joint origins published as frames that joints and other features name ({"mount": "F7:mount(end_b)"},Resolver::mount). Abound_lengthmeasures a ray from one part's frame to another's face or frame and sets its reference parameter as driven dimensions do, before the derived part that takes it as its length. Anedge_frame(mitcad#1814,features/edge_frame.rs) publishes two frames along a straight edge on a face, offsets kept as values: a member along an edge has its joint on one and its bound length to the other's plane, so it follows the body the edge is on. The rules that place, mitre, connect, size panels and list cuts plan everything against the document and make it in one undo step; components record what BUILD made (build). They work in the BUILD host (#394,Document::build_host): the active component when its policy takes components, else the nearest one up that does (in a new design Component1 itself, mitcad#421), so the design policy never refuses where a part goes; bound lengths count as assembly features there, as joints do. Everything else treats them as ordinary components, features, joints and parameters (commands.md, "BUILD: profile assemblies"). - Timber frames (mitcad#479,
core/model-build/src/frames.rs): a wall, floor or roof frame is a set of ordinary BUILD members (grounded members by two points, with plumb end cuts andbirdsmouthcuts in their derived parts) whose definition the lead member's record keeps (framing; each member'sframeandmember, its place in the frame). Laying a frame out is geometry from definitions only: a wall reads the walls it butts against and those that butt against it, a roof its two walls; an edit plans the frame and the frames that depend on it, keeps the members whose place stays (replace_member), makes and removes the others in oneapply, drives the fasteners throughbuild_connectand merges it all into one undo step (merge_undo) (commands.md, "BUILD: timber frames"). Since mitcad#522 each frame is a component of its own in the BUILD host (framing.component), its definition in that component's coordinates: its members are made there, and its fasteners are driven with that component as the BUILD host (Document::set_build_host_override) so their joints are inside it; frames saved before stay flat. The junction search reads a timber member's material as its box clipped by its end cuts (mitcad#521,build/junctions.rs), so cut ends meet sides by their cut faces and boxes overlapping where no material is make no junction. A wall's plate longer than its timber's longest is laid out as pieces over the studs (mitcad#536,Splicinginframes.rs): the studs are planned first, the plates' joints chosen over them (a backing stud added where none is in reach), and the pieces are ordinary members. - Timber fastener seating (mitcad#512,
build/wood.rs): the library'swood.seatselects a head-top or bearing frame. Legacy axis-aligned wood screws and nails infer the head-top plane from evaluated body bounds; pan/hex/washer heads keep the bearing frame. A joint override moves only the fastener's own frame, leaving the member's entry frame fixed. Swap recomputes it from the replacement's row. Boards are not machined for the intentional overlap;build_parts.seatingreports physical head-top and tip distances for inspection and UI acceptance. - Boundary Fill (mitcad#457,
features/boundary_fill.rs): aboundary_fillfeature fills the cells its tool bodies enclose, each picked by a point inside it (a cell: inside every tool that holds the point, outside the others).Kernel::boundary_cellsdivides space by the tools' faces once (OCCT'sBOPAlgo_CellsBuilder,geometry/src/boundary_fill.cpp) and gives each point's cell with the tools that hold it; the cells become new bodies or one tool that joins, cuts or intersects participants as an extrusion's does (commands.md, "Boundary Fill"). - Fill Cavity (mitcad#1818,
features/fill_cavity.rs): afill_cavityfeature fills a closed pocket of a body up to a cap plane with two booleans and no flood:Kernel::cavity_piecesgives the empty spaces of a box below the cap (the box less the body,geometry/src/fill_cavity.cpp), whose faces' names tell the model what each touches (the cap, a side or the bottom of the box, a seed face); the model chooses the closed ones, refuses one that opens out in words with its places, and joins them to the body (commands.md, "Fill Cavity"). - Surface modelling (mitcad#455, beside Patch, Stitch and Thicken of
mitcad#456): surface (sheet) bodies are ordinary bodies whose shape is
open shells;
Kernel::body_kindtells them from solids. Extrude, Revolve, Sweep and Loft make them withsurfaceset (features/surface_sweeps.rs): the walls of profiles are the solid feature's result without its caps (Kernel::open_faces), so the solid feature's options and names apply, and sketch curves are swept by the kernel's sheet methods (geometry/src/surface_sweeps.cpp). The families of surface features that change surface bodies follow the same pattern: a feature module, a block ofKernelmethods with a defaultUnsupported, and a geometry file of their own (surface_offsets.cpp,surface_edits.cpp,surface_fills.cpp; commands.md, "Surface modelling"); the application has them in the SOLID tab's SURFACE group. Free edges (of one face only) have no names: features take them as openings of the body, narrowed by faces and points (features/sheet_edges.rs). - Properties (mitcad#496,
core/model-base/src/properties.rs,document/properties.rs): typed key/value properties in named sets on components (the definition's), occurrences (their own values over their component's) and bodies, with the design's own types (allowed values, unit, default). ThePropertyStoreis part of the definition state (each owner's sets shared between undo steps until changed) and the design file (property_types,properties); its commands are undo steps that recompute nothing. Values keep canonical units and their source (user, an import,library,computed); computed values (volume, area, mass, a BUILD member's length) and a library component's data are worked out at query time and never stored, so a recompute never changes the file. Importers add theirs withDocument::import_properties(one step, merged into the import's); copies of components take theirs along (commands.md, "Properties"). - Design properties (mitcad#1088,
document/design_summary.rs,file/statistics.rs): the design's summary is the root's property setSummary(no state of its own); its statistics (created, last saved, by whom, with which MitCad) are kept beside the definition state, not in it (as the preview, below) (Document::statistics, read apart from the definition infile::load_parts): undo, design comparisons and plain saves leave them, and only a stamped save (Document::save_file_stamped, the application's Save) that changes the file sets them (commands.md, "Design properties"). - The design's preview (mitcad#1539,
model-base/src/design_preview.rs): the application's Save puts the 3D view's picture (a PNG, 256 px at most a side) into the file's top-levelpreview, kept beside the definition like the statistics and changed with them (Document::save_file_previewed: only when the file changes otherwise too). The file managers' thumbnailermitcad-thumbnailer(core/thumbnailer: model-base and the PNG writer ofcore/preview, no model, Qt or OCCT) reads only that field and scales it to the size asked for (app/COMMANDS.md, "The preview in the design's file"). Windows Explorer's thumbnail handlermitcad-thumbnails.dll(mitcad#1695,app/thumbnails, a C++ COM DLL) and the Finder's Quick Look extensionMitCadThumbnails.appex(mitcad#1696,app/platform/macos/QuickLookThumbnailProvider.mm, in the bundle'sContents/PlugIns,cmake/MacQuickLook.cmake) read it through the same crate's C ABI (thumbnailer/src/capi.rs, linked as the static librarymitcad_thumbnailer_capiofcore/thumbnailer-capi, Windows and macOS). - Reorient Design (mitcad#502,
core/model/src/reorient.rs,document/reorient.rs): the whole design turned by quarter turns as a rewrite of its definition, every component but linked ones in its own coordinates. A turn is a signed permutation of the axes, so nothing is rounded. References and paths turn wherever a definition holds them through their JSON form (geom_ref::to_turned_value: an origin datum becomes the one the turn takes it onto, else the fixed plane or axis there), positions and directions outside references per feature type, sketches on origin planes get their own frame, sketches whose plane's frame follows the model axes get one from the turned design's evaluation, base features a Move, occurrencesR · T · R⁻¹. The command computes the result and refuses it unless every body and occurrence is where the turn takes it (commands.md, "Reorient Design"). - Mortise and Tenon (mitcad#1012,
core/model/src/features/mortise_tenon.rs): no kernel method of its own. The model places the tenon on the end face from the face's plane and edges (Kernel::face_plane,Kernel::curves_of: the width along the longest straight edge, the face's extent for the centring and the fit), builds the tenon and the mortise (the tenon grown by the clearance, its corners round by the tool's radius) as regions in code extruded byKernel::extrude_feature, and changes two bodies in one feature: the mortise cut first (a tenon that reaches nothing is refused as such), then the tenon joined. A through tenon's length is where the mortise body ends along the tenon's middle (Kernel::segment_crossings). A count of tenons (mitcad#1063) spaces them along the face's long direction: their regions go into one extrusion per run of equal lengths (a compound of the runs for through tenons of different lengths), so the feature still cuts once and joins once (commands.md, "Mortise and Tenon"). - Envelope (mitcad#1271,
core/model/src/features/envelope.rs,features/envelope/wrap.rs,document/envelope.rs): no kernel method of its own. The kernel tessellates the source (Kernel::triangle_mesh); the wrap is plain Rust on a voxel grid of half the detail size (mark, close by one cell with the outside flood-filled between, make well-composed, take the surface in runs of flat faces), so it is tested without OCCT; Convert Mesh'sfaceted_solidmerges the surface into planar faces andKernel::boundary_bodybuilds the solid. The samebuildserves a linked component shown by its envelope (Document::set_link_envelope): its base feature then holds the one envelope body instead of the design's bodies, and the link records the detail size (ExternalLink::envelope), whichupdate_linksuses (commands.md, "Envelope"). Each occurrence chooses (mitcad#1276): one shown otherwise than its component goes into another component linking the same file (made for it when none is shown so), so a component holds either the design's bodies or one envelope and the renderer needs nothing of its own. Joint origins on the design's faces resolve in the component that shows it in full, or, when the component itself is switched, from the frames they had in full (ExternalLink::frames,joints::envelope_side). Bothlinkfields make a build before them refuse the design file.
The default is metric wherever a unit is chosen: document (mm), import and
export units, thread and hole tables (ISO first), materials and mass
properties, grid and settings. Inches only by choice. An imported file's
own units are kept. New designs start in the user's default units for new
designs (Preferences › General, mm by default, mitcad#1036): the unit is
the new document's initial state (Document::new_design_in, a project's
new_design with units), with no undo step and no modified mark.
The DXF exports (a sketch's, a Flat Pattern's, a face's, a cut sheet's and
a drawing's) write the design's own length unit unless the export names
another (units, mitcad#1408): an inch design's DXF is in inches
($INSUNITS 1, $MEASUREMENT 0), a millimetre design's in millimetres;
mitcad_model::exchange::dxf_in_unit scales the millimetre drawing.
The Kernel trait (core/model-base/src/kernel.rs) is grouped by feature
family. New methods default to Err(Unsupported), so the mock kernel
implements only what tests use. Bridges are split per family
(core/ffi/src/kernel/<family>.rs, geometry/src/<family>.cpp) and share
the Shape type.
- Inputs are plain structures: profile regions as loops of named segments
(
Line,Arc,Circle,Ellipse,EllipseArc,BSpline) plus aSketchFrame. Results areShapehandles whose faces carry names. - Query results are kernel-independent descriptions: a planar face's origin is the projection of the model origin; a surface of revolution's axis points along its largest component.
- Volumes and areas are integrated per face, span by span with fixed
Gauss rules (
geometry/analysis/src/face_integral.cpp, #140). The integral over the face's domain in the parameter space becomes one along its boundary curves (Green's theorem, as in OCCT'sBRepGProp) of an integral across the surface. Both are split where the integrand is not smooth or a piece would be too long for a fixed rule: across the surface at its knots (B-spline surfaces, the curves of extrusions and revolutions, the basis of offsets) and every eighth of a turn of an angle parameter; along a curve at its knots, where it crosses a knot line of the surface, and the same angle steps. Each piece gets Gauss points exact for a polynomial piece's second moments (8 for cubics), more for rational and offset geometry, and rational spans are taken in quarters (an area's square root has branch points near them). The number of points depends on the geometry only, so a face always measures the same; faces of every kind come within 1e-9 of their exact values in the tests. OCCT's rules do not follow spans: the fixed one takes at most 61 points across a face and along a boundary curve (a hole bounded by a cubic of 132 spans, an intersection curve stored in a file, took 141 mm² off its face, #139), and the adaptive one never refines across the face (its error estimate there starts at zero and is never set) and drops one span of a boundary curve of more than 1953 spans (a stored thread's crest bounded by helices of 2574 spans lost 1.4 % of its area). Where a boundary curve ends short of the vertex it shares with the next one, a gap the vertex's tolerance bridges in a valid shape, the loop in the parameter space is closed by a straight segment (#325: a fillet's blend face whose curve stopped 0.36 mm short of a vertex of 0.74 mm tolerance measured 4.38 mm² instead of 6.64, and the body 3.5 mm³ off the file's). Only FreeCAD's reference check measures with OCCT's fixed rule (fixed_point_properties), as FreeCAD does.Shapecaches its measured properties and bounding box behind a lock. Operations may read the same input shapes on several threads at once (the.f3dimport's workers, #95): they never modify their inputs, and those whose OCCT algorithms write into their inputs' sub-shapes work on copies (below). A shape must still not be triangulated while another thread computes with it (OCCT stores the triangulation in its faces). - Boolean results get coplanar faces and collinear edges merged, unless the merge breaks a result OCCT's checker accepted. Edges the operation leaves inside a face of its result, bounding no face (an edge of one operand lying on a face of the other, which OCCT's fuse keeps as an internal edge), are taken out of it (mitcad#1371): a later fillet over such a face gave self-intersecting wires.
- Faces on one surface (mitcad#1261,
join_same_surfacesingeometry/src/face_join.hpp): OCCT's merge after a boolean takes its linear tolerance from the fuzzy value, none for an exact operation, so pieces of one plane, cylinder, cone, sphere or torus whose surfaces lie more than a few 1e-8 mm apart stay separate faces with an edge between them (the arcs of a solved sketch's circle as a cut's wall, the wall going on from a rim), as do all faces where the merge broke the result. After Join, Cut and Intersect, fillets, chamfers and extrusions of several profiles, faces whose surfaces agree within 1e-6 mm and 1e-9 rad (whatever their frames), that face the same way and meet along an edge are joined: OCCT's merge with that tolerance, on a copy of the body, allowed to remove only the edges between them and to join only the edges along them. Before it, each piece of a cylinder, cone, sphere or torus is put on its group's first piece's surface (its edges' curves moved by the map between the two surfaces' parameters, u' = ±u + b, v' = ±v + d, the periods taken from an edge they share): OCCT's own move of curves onto another frame's surface is right only for cylinders (a torus or cone whose axis points the other way stayed apart). A face closed round its axis whose seam is in pieces at several angles (pieces joined with their seams apart, OCCT's merge included, which leaves the rim between two seams as an edge) is made anew with one seam by OCCT's shape healing. The joined face holds all its pieces' names, so a reference to any of them finds it. A group whose joined faces would not be valid stays apart, with an info of the result naming it; a group that would make a face winding round its axis more than once (the turns of a thread's root, a face each) stays apart without one. OCCT's merge leaves a face closed round its surface apart from an open piece of it that meets it where the closed face's seam runs on along the piece's edge (a pin extruded from two regions, its side one face with its seam where the regions met, on a plate's end of the pin's radius): such groups are joined again with every closed face cut in two first (ShapeUpgrade_ShapeDivideClosed), which the merge joins with the open pieces into one face closed round the axis (mitcad#1336). B-spline pieces (a thread's flanks) arejoin_surface_pieces' and are not joined here. - Local booleans (
geometry/src/local_boolean.hpp, modelled threads): OCCT's booleans rebuild the whole shell of a solid whose faces they split, and its checker visits every face, both quadratic in the faces. A small tool on a large body is fused or cut with only the body's faces whose boxes reach the tool's; the pieces are classified by the faces around their section edges (else by a point), the shell is the far faces with the kept pieces, and the checker sees only the faces that changed. Anything unusual (several solids or shells, a result that falls apart, a piece that cannot be classified) runs the ordinary boolean. Several tools, each one solid and with boxes apart from each other's, go into one local boolean (local_boolean_all), else each in turn. A modelled thread of several faces (mitcad#843,geometry/src/thread_options.hpp) reads every face from the body it is given; the tools of the faces whose reach (a box round all their tools can change) meets no other face's are built at once on OCCT's thread pool, each job an operation of its own under the caller's cancel source and from shapes of its own, and applied stage by stage (bands, chamfers, beyond the crest, grooves), a stage's tools in one local boolean; faces whose reaches meet follow one by one, each read from the body the one before left.MITCAD_THREAD_SEQUENTIAL=1threads every face so,MITCAD_THREAD_PARALLEL=0builds the tools on the calling thread,MITCAD_THREAD_MERGE=0applies them one by one; withMITCAD_BOOLEAN_TRACEeach thread printsthread-trace:lines (per face its tools', booleans' and checks' time, per thread its phases). - Booleans on perforated bodies (
geometry/src/far_features.hpp, #72): OCCT's boolean, the face merge after it and its checker go through every wire of a face they touch, some once per wire or per pair of wires, so a small cut into a plate with thousands of holes took minutes. A single target's holes away from the tool (far faces bounded by whole inner wires of other faces, such as the wall of a hole) are taken out first; the boolean, the merge and the checker run on the rest (a closed solid with those holes filled), and the holes go back into the faces that took their faces' place. Holes the merge could change stay (a neighbour in the same surface, a vertex between two edges along the same faces), unless the body is itself a merged boolean result (Shape::unified). A cut with many solids apart from each other (a pattern's copies) runs region by region, about 300 solids at a time, each cut seeing only the holes near it; when a face of the target splits into pieces or the target falls apart, it is one cut after all, so that the pieces' numbers are those of one cut. Results are the same faces, edges, names and volumes as without (geometry/tests/ test_far_features.cpp);MITCAD_NO_FAR_FEATURES=1turns both off for comparisons. - The material a near copy of a body lacks
(
geometry/include/mitcad/geometry/removed.hpp, #85; the import's history-based hole guess: a replayed body minus the body stored for its next state). Where the faces of two bodies nearly coincide, OCCT's boolean walks along every such pair of free-form faces, seconds each, and its result is often wrong. The cut runs only in boxes around the faces where the two differ by more than a slack (new faces with a point farther than that from the other body's faces; faces gone with every point that far): both bodies are cut down to the boxes first. A piece that reaches the side of its box grows the boxes; boxes taking half the body's run the whole cut. - The join of a body with a near copy (same header, #88; a
mirror's
combineof a nearly symmetric body with its image): where at most half the faces of each differ from the other's by more than 0.1 mm, only what the copy adds there is joined to the body (the copy minus the body in boxes around those faces, as above, slivers between near-coincident faces left out); no such face, the body itself. Other copies are joined whole. - Joins with several bodies near the tool first find the bodies it
touches (
touchesingeometry/src/boolean.cpp) and fuse only those. - A union of several bodies (
unite, acombinejoin with several tools; #400) joins the bodies whose faces are all elementary (planes, cylinders, cones, spheres, tori) first and the bodies with free-form faces then with their union, its faces merged. OCCT's boolean intersects every pair of faces that meet: a spiral stair's slabs and treads, whose rims a sketch's lines split into hundreds of faces on one cylinder, met its helical stringers lying on that cylinder piece by piece (5 664 face pairs for seven slabs, eight treads and two stringers ingeometry/tests/test_helical_joins.cpp, 309 joined first). OCCT's face merge builds a ring of cylinder pieces cut through from end to end (the stringer's band along the rim, the treads rising on it) as one face without a seam (port patch 0680); before, it built such rings with seams, the result was invalid, and the union was computed again without the merge, keeping every piece. Theinterferencequery's booleans of pairs of bodies run on all cores, as the model's do (such a slab against the stringer took 2 s on one). - A union of several bodies (mitcad#1273,
geometry/src/union_groups.cpp) first groups them by their boxes: bodies whose boxes meet, directly or through others, are one group (a union within a tolerance widens the boxes by it). Each group of several is united on its own, the groups beside each other on OCCT's threads, and the groups' results, which share nothing, are put together as one compound without a boolean operation; a union of bodies all apart is a compound at once, as before. A union that lost material of its bodies (no solid where they have some, or, where OCCT warned, less volume than the largest of them) or whose pieces OCCT left unused (BOPAlgo_AlertFaceBuilderUnusedEdges,BOPAlgo_AlertSolidBuilderUnusedFaces), or where sub-shapes of one body came to meet (BOPAlgo_AlertAcquiredSelfIntersection: a mount whose stud stands coaxially in a carriage's threaded hole stayed a solid of its own), is wrong whatever the tolerance. The bodies whose boxes reach those places are united first, place by place, and the union of all is made again, exactly, with those unions in their places; a union of a few bodies, or one whose places reach all of them, tries fuzzy values from 1e-4 mm up to 1e-3 mm (or its tolerance) and takes the first sound one (with 1e-5 mm the carriage and the mount gave one solid that missed most of their common volume, without a warning). Where none is, a union that lost material fails (the union of the shapes gave an empty result,the union lost material of the shapes it joins) and one that only left pieces unused stands as before. OCCT's exact union of a nut lying inside a threaded carriage, its bore's seam a few micrometres from the vertices of the thread's faces, came out with no solid, a result its checker finds valid; two copies of a plate whose sides lie 1e-4 mm apart joined to the lower plate alone. A join (boolean) of targets the tool touches that gives no solid is retried with the fuzzy values of a join that loses volume and fails when it stays empty. Combine fails a join, cut or intersection of bodies with material whose result holds no solid ("the join of 257 bodies gave an empty result"), keeping the target and the tools, for any kernel. The face merge after a union of thousands of faces spent most of its time in ShapeFix's orientation of the shell's faces, which went through the whole shell after every face (port patch 1270); the union's own single-threaded parts, the stick vertices of each pair of faces and the solid classifier that places the result's cavities and checks its shells, are faster with port patches 1280 to 1284 (mitcad#1279: the union of 257 bodies 17 s → 12.9 s, the same result). The union is made once and named both before and after its faces are merged (the merge works on copies,SetSafeInputMode): where the merge breaks it, the union as OCCT left it is taken without making it again. The reported join's merged union (7 458 faces) was taken for broken so, and kept as OCCT left it (8 721): OCCT's solid classifier, in the checker's test that each cavity lies outside the others, gave up on a point of a cavity in the plane of two far cavities' bottom faces and counted it as outside; such a point is now classified along fixed lines through the shape's box (port patch 1285, mitcad#1280). The bodies with free-form faces are joined after the elementary ones (#400) only when there are a few of them (at most 4): a machine's 30 such bodies among 257, each meeting a few others, took two unions of most of the bodies so, and a fault between a body of the first union and one joined after it could only be mended in the union of all. - Near misses before a union of many (mitcad#1278,
near_missesingeometry/src/union_groups.cpp): before the union of a group of 8 or more bodies, every pair whose boxes meet is looked at, on all cores, for a vertex of one that lies near a face of the other but not on it: farther from the face than their tolerances together (which an exact boolean takes as touching), no farther than 1e-3 mm. The pairs found, and those linked through each other, are united first, beside each other, each exactly where that is sound and else with the fuzzy values above; the union of all is then made once, exactly, with those unions in their places. Found only in the union of all, those places took a second union of all: the reported 257 bodies' join took two unions of some 10 s each (35 s in all), and now takes one (25 s, 1.7 GB at most). The vertices' distances to the faces near them took 0.3 s for the design's 709 pairs and found the 7 pairs whose exact union OCCT gets wrong, no more; uniting each of the 709 pairs to find them took about 100 s of CPU time. A place the near misses miss is still found by the union of all and mended as above. A checked union's result is marked as found valid (Shape::checked_valid), so that operations on it check only what they change. A cut or an intersection of a target with a tool (boolean) that OCCT left pieces of unused, or where sub-shapes of one operand came to meet, is wrong as such a union is: it is made again with the smallest fuzzy value from 1e-4 mm up to 1e-3 mm (or the caller's tolerance) that leaves nothing unused, and where none does the exact result stands. Two copies of a plate whose side walls lie 1e-4 mm apart, one cut by the other, came out whole and as nothing, and their intersection empty. - Large bodies (#181): OCCT's checker runs on OCCT's thread pool
(its jobs count their failed allocations as the calling thread's,
#132), where it checks whole bodies (operation results, the
bodies built from files); on one thread checking a stored body of
23 000 faces took 37 s. A cut whose tool passes a body by (no face of
it modified or removed) is not checked: its result is the body as it
was, which the caller leaves alone (before, such a body that the
checker rejected, a stored body invalid already, failed the whole cut).
Booleans do not check their solids for being inverted
(
SetCheckInverted(false): the check built a point classifier of all of a solid's faces on one thread, every operation). The.f3dimport heals a stored body of 256 faces or more only where it differs from its build in the history state before (brep::Healed; that base is fixed by the file, not by the order of the builds, #243;core/import/docs/f3d-performance.md). A shape of 64 faces or more finds its faces by a reference through an index of its face names, made the first time it is asked (Shape::find_faces); before, each lookup read every face's names, and finding the faces of a large body one by one was quadratic in its faces. Measuring the distance of a tool face to a face with thousands of holes classifies points against all of its edges for every pair, so when the target's faces near a tool solid have 1,000 edges or more, up to 32 of the solid's vertices are classified first: one inside the target, or on its boundary within 1e-6 (measured), shows the touch; otherwise the faces are measured as before, so the answer is the same (#77). - Patterns leave out of a cut (and of Adjust's join, which skips copies that reach no body) the groups of copies whose boxes stay more than 0.1 mm from the boxes of all participants, before the copies are united: they change no body, and a large pattern of holes over a round plate had most of its copies off the plate. Copies whose boxes come that near each other are kept or left out together.
- Patterns leave out a copy that is the same solid at the same place as
its original or as a copy kept before it (mitcad#1588,
coincident_copiesincore/model/src/features/pattern.rs): a body of revolution turned about its own axis, or two products of a circular pattern about two axes on one place. A join of two equal solids whose surfaces are parametrized differently (two spheres with their poles elsewhere) goes through faces that lie on each other, where the kernel's booleans are least reliable; such a copy adds nothing, so no boolean is made. Only copies that turn or mirror their object are compared, first by their centres of mass and tight boxes, then by points on the faces of each against the faces of the other (Kernel::face_points,Kernel::boundary_distances); a kernel that cannot measure makes every copy as before. - A pattern of several features (mitcad#855,
Copying::togetherincore/model/src/features/pattern.rs) applies a run of consecutive features that all join, or all cut, the same one body in one boolean: each feature's copies united as before, the features' tools as one compound. The cost of a join or cut follows the target, not the tool (a 6-face tool into a body of 3 000 faces took 1.5 s), and a pattern of a dozen join features made a dozen such joins. The run is taken only where it is the same as the features one after another: the boxes of the copies of different features stay more than 0.1 mm apart, so each feature acts on a part of the body the others do not touch; it made no body; every feature's copies have faces in the result; and a face of the body split into pieces (named#kin their order) has one feature's copies near its box only, so the pieces are numbered as that feature alone numbers them. Otherwise the body is restored and the rest of the pattern goes one feature by one, so a pattern wastes at most one boolean. The last condition is foreseen from boxes before the boolean: a run ends before a feature whose copies come near a face of the body (Kernel::face_boxes) that another feature's copies come near too, unless all those copies stand inside the face (a flat face whose box holds them across it: bosses and holes on one face).MITCAD_BOOLEAN_TRACEsays for each run why it was not taken or kept.MITCAD_NO_PATTERN_RUNS=1turns it off, for comparisons. A cut run counts as many passes over the body as its features (the split pieces' memory, #408). - A pattern's optimized compute option with fillets or chamfers among the
features copies the faces they made instead of rounding at each copy:
Kernel::feature_changesgives the material the features added and removed (geometry/src/face_copy.cpp, onremoved_material), the copies are moved and joined or cut in one operation each, andKernel::supported_copiescuts off the material of a copy over a part of its seam that no face of the body lies under (a rounding that fails on the 146th of 1,078 copies is never worked out again there). - Transforms check their input once (
Shape::checked_valid) instead of every copy: a rigid motion, mirror or uniform scale keeps a valid shape valid, and checking each of a pattern's copies was four fifths of their time. A copy that only renames faces (a tool a pattern rebuilt in place) shares the input's B-rep. - A general affine map (a non-uniform scale) of a body with a sphere maps
it exactly where it can (mitcad#1504,
geometry/src/transform.cpp): a sphere whose axes stay at right angles, the two about its axis equally long, becomes the ellipsoid of revolution with the sphere's parameters (a surface of revolution of half an ellipse), its circles circles or ellipses, B-splines their moved poles; other bodies go through OCCT'sBRepBuilderAPI_GTransform, which converts every face to a B-spline (a sphere flattened by 0.1 came out with an unorientable face). A face the checker calls unorientable names the problem of its edge or wire in it that made it so (util.cpp,first_problem), in the error's detail only: a person reads "… produced an invalid shape" (mitcad#1851,require_valid's placed error). - A taper whose walls meet or vanish within the extrusion (mitcad#1851,
geometry/src/taper_events.cpp, called bysweep.cpp'stapered) where OCCT's draft fails, comes out invalid, or (a valid draft) the profile's offset at the far end (BRepOffsetAPI_MakeOffset) shows walls meeting or vanishing on the way: the prism with (widening) or without (narrowing) the wedge each wall sweeps (a line's a polyhedron, an arc's its section revolved, ending at the centre where the arc vanishes, any other curve's ruled to its offset curve and sewn) and a pyramid at each corner whose offsets part, its sides in the two leaned planes. The booleans resolve the topology events: no slicing at the event heights, whose sections are degenerate (zero-width slits). Results without such an event are the draft's as before. Emboss's projected taper on a plane parallel to the sketch along its normal, and a taper alone along a straight sweep path, fall back to the same extrusion taper where their own offsets lose edges (emboss_projection.cppplanar_tapered,path_sweep.cppstraight_taper_sweep). - A wrapped Emboss's taper and a taper alone along a smooth curved sweep
path whose walls meet or vanish (mitcad#1854) are that extrusion taper
built straight and flat, then bent through a smooth map of space
(
geometry/src/space_map.cpp,mapped_solid): the emboss's profile laid out on the top's development and a point h up taken h / depth of the way from the foot to the top at its parameters (emboss.cppwrapped_events); the sweep's straight taper along the profile's tangent and each place a along it taken to the path's frame a further on (path_sweep.cppcurved_taper_sweep, its frames as the lofted sweep's).BRepTools_Modifiercarries the shape face for face: each surface replaced by OCCT's approximation (GeomConvert_ApproxSurface, C1, within 1e-7 of the shape's size) of the map of it over the face's own parameters, so that the curves on surfaces stay; each edge's curve likewise (GeomConvert_ApproxCurve); the map's derivative by central differences. Caps the map takes onto known surfaces (the foot and top cylinders or cones, the sweep's planes moved rigidly) are laid on them exactly, their curves on the surface refitted, so that a boolean with the body meets them as before. A path of several curves is bent slab by slab (split where the curves meet, where the bend's derivative jumps) and the slabs fused. Where the old construction fails and this one cannot build either, the error says so in words (the taper closes part of the profile on its way, …;taper_events.cpp). - Checks where a boolean changed the body (#121,
geometry/src/ util.hpp,is_valid_where_changed): a shape the checker found valid says so (Shape::checked_valid: boolean results, roundings and chamfers, the bodies built from files). A boolean whose targets are all such gives the checker only the result's faces it does not share with them and the faces that meet those at a vertex, and counts over the whole result that each shell is connected, holds no face twice and has one face on each side of each edge running along it in opposite directions. A face the result shares, and whatever only such faces use, is as it was checked (the non-destructive boolean leaves its inputs' sub-shapes alone, and the face merge changes only what the faces it merges use), so the answer is the checker's on the whole shape. Where the result is not solids of shells, any of that does not hold, or most faces changed, the whole shape is checked; a solid of several shells (a body with a void) is also checked as a solid, how its shells lie in each other (BRepCheck_Solid, mitcad#855). A solid of a shape found valid is valid (geometry::solids). On bodies of 5 000 faces the whole check took seconds after every join and cut. - A shape keeps its faces' kinds and areas once measured
(
Shape::face_measures,face_infosmeasures them on all cores), and its optimal bounding box is its faces' boxes found on all cores (the same box as OCCT'sBRepBndLib::AddOptimal): the.f3dimport asked for the faces of the same large body dozens of times an extrusion. - A shape also keeps its edges' middles and curves once worked out
(
edge_middles,edge_geometries) and a box that holds each face (face_boxes,Kernel::face_boxes, on all cores; faces of offset, swept and other surfaces get unbounded boxes): the.f3dimport's lookups of a face through a point pass over the faces whose box lies farther than the tolerance, instead of measuring the point's distance from each of a body's 23 000 faces (#119, performance.md). - Operations must not modify their inputs. Several OCCT algorithms
write into input sub-shapes (p-curves, tolerances), which made a feature
give a different B-rep depending on what ran before. Merged booleans,
fillets, chamfers, shells, lofts from faces and shape healing therefore
work on copies (
detail::InputCopy,detail::working_copyingeometry/src/history.hpp).MITCAD_CHECK_INPUTS=1fingerprints inputs before and after every operation and reports changes on stderr (geometry/include/mitcad/geometry/input_check.hpp); geometry tests run with it. - OCCT crashes become errors where possible (
catch_occt_crashes; on Linux and macOS needsOCC_CONVERT_SIGNALS, defined in the rootCMakeLists.txt; on macOS a fault is SIGSEGV or SIGBUS). Handlers are installed on the app's model worker thread, on its section worker's thread (mitcad#438), on its UI thread at start (app/main.cpp), inmitcad-cli'smainand on the import's threads. The analyses the app asks for run as operations too (#392): the analysis bridge (core/cpp/bridge/analysis.cpp) runs section, clip, measure, distance, interference and physical properties throughgeometry::run_operation(guard.hpp, the public form ofrun), so a crash in Section Analysis' booleans is an error: the body is shown whole and the panel shows the error. Section Analysis clips and sections the bodies shown together on OCCT's thread pool, each body its own operation there (analysis_clip_all,analysis_section_all, mitcad#438), and skips the booleans of bodies the plane does not reach (from their kept boxes); the calling thread's cancel source (geometry::cancel_source) reaches each task, and the tasks not started once it is set fail as cancelled. For Section Analysis off the UI thread,analysis_detach_all(Kernel::detach_all) detaches the bodies first, on the thread that owns them: a copy that shares no sub-shape with a body the plane may reach (geometry::independent_copy, with the same names, its box, its mesh faces' triangles), and of a body the plane passes only its kept box. The crash that was reported came from mesh bodies: OCCT's booleans need surfaces and read a null handle on a face without one, so the analysis sections and clips mesh bodies on their triangles instead (geometry/analysis/src/mesh_section.cpp).MITCAD_TEST_OCCT_CRASH=<operation>forces a crash (cli.occt_crash,cli.occt_crash_section,geometry.guard_operation,tools/ui-section-crash-test.shwithclipandsection). On Linux and macOS OCCT's handlers are the process's; a crash outside an operation that catches it (Standard_ErrorHandler::IsInTryBlock) goes to the handler installed before them, the application's crash report (below), instead of OCCT's "no catch was found" exit (geometry/src/guard.cpp,geometry.guard_*). On Windows OCCT's handlers (the unhandled exception filter, the C runtime's signals) turn a fault into an exception only on a thread running an operation (runingeometry/src/util.hpp) and on OCCT's own threads while one runs; any other fault goes to the filter installed before them, the crash report, with the stack from the fault. - C++ exceptions never cross the bridge (mitcad#937). Every
#[cxx::bridge]with anextern "C++"block includescore/cpp/bridge/trycatch.hpp(include!("bridge/trycatch.hpp"); a new bridge does the same), which overrides cxx'srust::behavior::trycatch: the shim of each C++ function returningResultcatchesStandard_Failure(its message, or "OCCT exception " without one),std::exceptionand anything else ("unknown C++ exception"), and Rust gets anErrthat becomesKernelError::Failed. cxx's owntrycatchcatches onlystd::exception, so an exception of another type, thrown by a bridge function that calls OCCT or the geometry's helpers outsiderun_operation, would have reached the shim'snoexceptand ended the process. OCCT 8.0.1'sStandard_Failurederives fromstd::exception, but the boundary does not rely on it.core.bridge(test_exceptions_across_the_bridge, throughcore/ffi/src/kernel/exception_probe.rs) throws each kind. - Where OCCT cannot impose what a feature asks, the geometry builds the
surfaces itself (
geometry/src/skin.hpp: interpolation with end derivatives, Gordon surfaces). Lofts with end conditions or rails (loft_skin.cpp), asymmetric and curvature-continuous fillets (blend.cpp) and setback/blend corners (corner.cpp) are built so; free lofts stay OCCT's through-sections. - Import of STEP assemblies (mitcad#1274):
Kernel::read_file_structurereads the file once (geometry/ioread_step_structured) and gives each distinct part's bodies once, in the part's coordinates, with the instances that place parts and sub-assemblies; the model (core/model/src/exchange/assembly_import.rs) makes a component per part (its bodies one base feature) and an occurrence per instance, so repeated parts share one B-rep in memory, in the design file and in the display meshes. Files without an assembly come as bodies, asKernel::read_filereads them. Into a design with content, the import is wrapped in a component named after the file (mitcad#1629,Document::import_file_wrapped,import_file'swrap). - Export: 3MF and STL are written by the model from
Kernel::triangle_mesh(one closed, outward-facing mesh per body, placed by its occurrences). STEP, IGES, OBJ and BRep go throughKernel::write_filewith each body's placements (ExportBody::placements; STEP as an assembly, the others as moved copies); STEP of bodies that occurrences place goes throughKernel::write_step_treeinstead (mitcad#1915,core/model/src/exchange/step_tree.rs): the design's component tree, each distinct component once as a part or an assembly instanced by its occurrences, as the import reads it back. USDZ is written by the model fromKernel::face_meshes(each face its own vertices with the surface's normals, in the orderKernel::faceslists them, so face appearances find their triangles; a mesh body's texture coordinates, its UV nodes, asFaceMeshes::uvs, mitcad#1874): a mesh per placement underXforms of the occurrences, materials from the appearances (core/model/src/exchange/usdz.rs,core/usdz); withanimation(mitcad#1597,exchange/usdz_animation.rs) the occurrences' and bodies' placements are time-sampled, from poses given or from a motion study's steps evaluated apart from the document (Document::study_placements), the meshes written once. Drawings (mitcad#471,export_drawing):Kernel::project_viewgives a view's edges with hidden lines removed (OCCT'sHLRBRep_Algo, lines and circles exact, other curves as polylines;HLRBRep_PolyAlgoon a triangulated copy when asked or when the exact one fails, for mesh bodies, and for a drawing's views of bodies with free-form faces, where the exact one took half a minute a view, or with many B-spline edges against many faces (mitcad#1033) (ViewSpec::quick, mitcad#962; its segments fitted back into lines and arcs,docs/performance.md) and a section's cut faces (Section Analysis'analysis::clipandanalysis::section),Kernel::round_holesthe holes (coaxial cylinders with the material outside, a counterbore or countersink beside them); the drawing crate (core/model-drawing, no geometry library) lays the sheet out (views by the projection method, sizes, callouts, the hole table with thethreadsquery's threads, the title block) and writes PDF and SVG itself and DXF throughcore/dxf. An export lays out a temporary drawing and draws it as a drawing kept in the design is drawn (below, Drawings in the design). - A mesh body (STL, OBJ) is a face with a triangulation and no surface.
geometry::transform_shapemoves a copy of the triangulation, and the validity check skips such faces. Surface operations do not take one (#399): the features refuse a mesh body they name, with its name, and leave mesh bodies out of all bodies (core/model/src/features/surface_bodies.rs, throughKernel::body_kind); the geometry facade refuses faces without surfaces before OCCT's booleans, dressups and face operations get them (detail::require_surfaces,geometry/src/util.cpp); and the app's inputs of those features do not offer them (InputDef::withoutMeshes, the pick item's geometrymesh). Convert Mesh (mitcad#462,features/mesh_convert.rs) rebuilds a mesh body of one profile extruded straight as a solid: the section is found in Rust fromKernel::triangle_mesh(adapted from SolidCraft,third_party/solidcraft/mesh_convert.rs) and built byKernel::extrude, so the faces are named as an extrusion's; no kernel function of its own. Its Faceted solid mode (mitcad#1082,features/mesh_convert/faceted.rs) takes any closed mesh: welding, orientation and the merge into planar faces are Rust, the solid isKernel::boundary_body(the IFC import's builder) adopted under the feature's face names, a new body; adding the feature hides the mesh body in the same undo step (document/mesh_convert.rs), keeping a Show When condition of the body, which it holds back while the conversion is in the timeline (mitcad#1157). The app's panel and Insert Mesh's Convert to solid make it.
References to faces and edges are names derived from how faces came to
be; edges and vertices are named by their faces. Face names travel through
OCCT's history (Modified/Generated), and edge names are rebuilt from
neighbouring faces, so a reference survives a rebuild with new dimensions.
Grammar: core/model-base/src/topo.rs. C++ treats names as strings, carries
them through operations and derives edge names.
Face name: <feature uid>:<role>[(<key>)], e.g. F3:side(c1[c4,c2]).
| Feature | Roles |
|---|---|
| Extrude, revolve, sweep, loft | side(<segment>), start(<region>), end(<region>); a parallel sweep turning back turn(<region>) |
| Thin extrude | outer(<segment>), inner(<segment>), mid(<region>); along curves (mitcad#463) outer(<curve>), inner(<curve>), tip0(<curve>), tip1(<curve>), caps start(r{<curves>}), end(r{<curves>}) |
| Extrude of a body face (mitcad#535) | side(<edge of the face>), start(<face>), end(<face>) |
| Fillet, chamfer | fillet(<edge>), chamfer(<edge>), corner(<vertex>) |
| Hole | hole<i>.wall, .tip, .cbore_wall, .cbore_floor, .csink, .top; thread thread(<face>) |
| Shell | offset(<face>), offset_cap(<removed face>) |
| Replace face, split | replace(<face>), split, split(<tool face>) |
| Pattern, mirror, copy | inst<i>(<original face name>); a pattern of a pattern nests: F6:inst1(F5:inst2(F4:side(c1))); a fillet or chamfer among the objects, repeated on the copies' edges (#105): fillet(<copy's edge>), chamfer(…), corner(…) |
| Pipe, coil | side<i>, inner<i>, start, end |
| Primitives, bounding solid | top, bottom, side<i> |
| Imported body | import(<i>) |
| Boundary fill | none of its own: a cell's faces keep the names of the tool faces they are pieces of |
| Fill cavity | fill(<cap face>) (fill for a plane cap) on the filled top; the box's fill_side(<k>) and fill_bottom only on the empty spaces it chooses from |
- Segment: the part of a sketch curve in a profile,
<curve>[<start>,<end>], bounded by the curves it ends on in the curve's direction:c3[c2,c4]. Several curves at one point:c2+c5; free end:-; whole circle:c5. - Region: sorted set of the outer loop's segments,
r{c1[c4,c2],c2[c1,c3],…}. A key that no longer exists is traced on the current curves (sketch::regions::Layout, #407): its segments as stretches of their curves between the same neighbours; when they close a loop, the regions inside it are its pieces (a region an edit split stays selected whole), less a hole the edit took across the outline (an area the other curves bound alone, holding no corner of the loop and lying mostly inside it, mitcad#1740); else the region with the most curves in common. The main piece keeps the old key, and the feature warns. - Renamed faces (#272,
core/model/src/features/renamed.rs): a sketch edit that gives a segment another neighbour renames its side face. A face reference that finds no face takes the face of the same feature and role whose key has the most curves in common (a side face: the same own curve, then the most end curves in place; names in keys alike), only when that face is unique: a tie fails with the candidates. An edge finds its two faces so and takes the edges between them (one with#k, all without); a vertex its faces. The reference keeps its stored name and the feature warns (… found as … after a change in Sketch1). Every feature that resolves a face, edge or vertex on a body goes through this one resolver; face appearances use the same likeness but take every tied face. An edge found by none of these still fails; its error lists at most five existing edges that share one of its found faces, best first, as suggestions that nothing takes (mitcad#1187,with_edge_suggestions). - A face may carry several names. When a boolean splits a face, pieces get
#kin geometric order; a reference without#kmeans all pieces. The order (piece_order,geometry/src/util.hpp) compares the pieces' centres of mass in X, Y and Z, then the lower corners of their boxes, their areas and the upper corners, each only where two pieces differ by more than 1e-4 mm: pieces within that of each other in one component are ordered by the next. So pieces lying symmetrically (alike in X, apart in Y) are not numbered by the nanometres of noise an upstream change leaves in X (mitcad#895: a chamfer lost its edge when a frame's two start pieces swapped#0and#1). Pieces whose deciding components differ by more than 1e-4 mm keep the order of the rounded centres used before, so existing designs keep their numbers. A reference that matches several faces lists them in this order too. A face a fillet or chamfer consumes, where the blend runs along the face's far edge (a face as wide as the blend or narrower, #121), gives its names to the blend's face, so its edges keep their names. - A modelled thread numbers its pieces (a crest, two flanks and a root a
turn) by their place along its axis, comparing centres and areas only
where they differ by more than 1e-4 mm, so that rounding noise, which
differs between platforms, decides no number (mitcad#490). The numbers
start at the pieces' count; the pieces whose number of the earlier
order (centres of mass in X, Y, Z) held on every platform keep that name
too, and the old names of the other pieces find no face. Each piece is
also named by its place from the nearer end of the face,
low_thread(<face>)#korhigh_thread(<face>)#k(mitcad#1231); these names sort first, so the edges at the thread's ends keep their names when its piece count changes, and an edge saved with a number along the thread finds the end's edge again (core/model/src/features/renamed.rs). - Edge:
E{<face A>|<face B>}(sorted),#kwhen the same faces meet more than once; a seam has the same face twice. Vertex: the set of faces meeting at it,#klikewise. Sorting is byte-wise in both languages. The#kof edges and vertices follow the same tie-tolerant order as a face's pieces (edge_order,vertex_order,geometry/src/util.hpp, mitcad#896): an edge by the point in its middle in X, Y and Z, then its centre of mass, its length and its box; a vertex by its point. Each component tells two apart only where they differ by more than 1e-4 mm, so two symmetric edges between the same two faces (alike in X, apart in Z) are not numbered by nanometres of noise in X; where the deciding components differ by more, the order is the earlier one of the rounded keys, so existing references keep their edges and vertices. A reference without#klists them in this order. - Splitting a body: the first time, the first piece in geometric order
keeps the body id and the others get ids of the splitting feature. The
feature remembers each piece's volume and centre of mass (saved with it
as
split_pieces), and later evaluations give the ids by matching the pieces with the remembered ones, so an upstream edit that reorders or changes the pieces keeps later features on the same pieces; a body that becomes another piece warns where it is named, and a piece no longer made is passed by (remove body) or fails its readers, its id given to no other piece (#408,core/model/src/features/pieces.rs). The memory is a cache read of the feature (Read::Pieces) that fits both the memory evaluated with and the one left, so taking it into the document costs no second evaluation. - Imports resolve the source file's references geometrically against the replayed body and store MitCad names.
A sketch definition (SketchDef, core/sketch/src/def.rs; the sketch code
is the crate core/sketch, mitcad#780) is stored; its evaluation
(core/model/src/features/sketch.rs) is not.
- Plane: origin plane, construction plane or planar face, with an
optional frame relative to it (imports keep the source's exact frame),
and an optional placement after that frame: an offset along the
normal, a move, a rotation and a flip, each value a parameter of the
sketch (
sketch/placement.rs; Redefine Sketch Plane moves a sketch to another plane and places it there,sketch.redefine_plane, mitcad#787). Or a cylindrical or conical face in its developed coordinates (SketchPlane::Developed, mitcad#1768): the arc length around a cylinder and the distance along its axis, a cone's development. The development (core/model-base/src/developed.rs) is worked out from the face at every evaluation (features/developed.rs) and kept inSketchOutput::developed; the sketch itself is solved and cut into regions on a carrier plane parallel to the axis (SketchOutput::frame), and every way onto the face is the emboss wrap's map of that plane: the kernel's wrap of profiles (Extrude, Emboss), the sketch's curves as curves on the face (paths, projections into other sketches: lines, circles and helices exactly, other curves as fitted B-splines), Split Face's bands (Kernel::wrapped_curves), and back, edges projected into the sketch as their developments and thesketch_surfacequery's rays and points. Features that take profiles or curves in their plane refuse such a sketch. - Entities: point, line, circle, arc (centre/start/end, CCW), ellipse,
elliptical arc, spline (fit or control points, degree, weights, knots; a
fit point spline may be closed: periodic, C2 through its first point,
mitcad#783), text, projections (optionally linked). Flags
constructionandfixed. Points are entities and curves refer to them, so a shared point is a real connection. - Constraints: coincident, horizontal, vertical, parallel,
perpendicular, tangent, equal, fix, midpoint, concentric, collinear,
symmetric, smooth; a tangent or smooth may name the point (an end of the
curves) it applies at (mitcad#783). Dimensions: distance (aligned, horizontal,
vertical), length, angle, radius, diameter, arc length. A driving
dimension is bound to a parameter (
d<n>); a driven one only measures, into a read-only reference parameter that features after the sketch can use (#231), and the sketch's own driving dimensions that cannot move what it measures: the sketch then solves in stages, the users of unknown references left out until those are measured, and a dependency cycle (by constraint connectivity through entities not already fully constrained without the users) is refused (mitcad#1116,mitcad_sketch::driven). A definition may name a user parameter as a driven dimension's reference, which the sketch then takes over: the importers map a source file's parameter of a driven dimension so (#250). A constraint or dimension can be inactive: kept and shown, left out of the solve until it is activated; the importers make those the source file's own geometry does not meet inactive instead of dropping the sketch's constraints (mitcad#721). - Stored positions are the last solution and the next solve's start, so the same definition always gives the same geometry.
- Implied constraints: a new constraint the others imply in full (it
raises the redundant count and takes no degree of freedom away) is
refused; one they imply only in part replaces the older geometric
constraints it makes redundant (never a dimension, a fixed entity or a
constraint on projected geometry), in one undo step (#287,
SketchEdit::drop_implied), else it is kept with its redundant part listed (mitcad#1774,SketchEdit::require_needed,edit::Freedom). - Line distances between lines that are not parallel are listed in
the status (
not_parallel) and warned about (mitcad#1774). - Conflicts in words (mitcad#1566,
sketch/conflict.rs): a conflict is told by constraint types, the entities they are on and dimension values, never by ids; fixed geometry summarised. An edit refused for a conflict names the user's constraints and dimensions that block it (SketchEdit::refusal: each left out in turn, those that let the sketch solve with the least movement) and lists their ids on a last line ([conflicts: k5]) that the application takes off and paints.
Evaluation: resolve the frame; compute projections (linked ones follow their sources by topological name); solve from the stored positions; report DOF, fully constrained entities, conflicting and redundant constraints (a conflict is an error, the last geometry is still shown); cut profile regions from the planar arrangement of non-construction curves (half-edge structure, leftmost turn; islands are separate regions; overlapping pieces and curves on each other, such as a circle drawn twice, count once).
For a sketch on a planar body face, evaluation additionally obtains the
face's named boundary curves (Kernel::face_boundary) and projects them
into the current sketch frame, including the plane's occurrence link.
These transient curves never enter SketchDef, its entities or its solve.
The same arrangement splits the face by the sketch's non-construction
curves; adjacency and boundary-crossing parity retain the face's material
(excluding holes) and the sketch's own closed regions outside it.
Coincident pieces keep both face-boundary and stored-sketch provenance;
their identity stays that of the stored curve, so a closed sketch region
sharing an edge with the face also survives removing that face support.
CurveId::FaceEdge holds a FaceBoundaryRef: a normal topological edge
(Named, spelled b{E{…}}) or an eligible one-sided profile boundary
(Profile, spelled b{O{<source face>|<source segment>}}). The latter
uses the actual ProfileFace::edges construction mapping when a planar
Patch is made, not a geometric match, transient edge index or fabricated
adjacent face. A profile Patch's references come from one sketch, so its
creating face and source segment together identify that sketch namespace.
Geometry stores this provenance separately from ordinary two-face edge
names, carries it through explicit OCCT history and transformations, and
persists it with cached shape metadata. Ordinary edge/face selection
grammars and existing b{E{…}} keys remain unchanged. Face edges in hole loops also
belong to a face-bounded region's key, so removing the supporting face
cannot accidentally select the sketch's whole former outer region.
The other way round, a key without face edges that the face's edges now
cut (saved before they bounded profiles, or a face that changed under the
sketch) is found among the regions of the sketch's own curves alone
(SketchOutput::own, computed on first use): it keeps its whole region,
not the face-bounded piece most like it (mitcad#1182).
Component/design copies remap the feature owners in bare profile region
keys as well as nested face, boundary and source-segment references,
rebuilding canonical edge and segment-neighbour order. Curve and glyph
ids stay local to the copied sketch, and derived-part source names keep
their original document's namespace.
Both profile queries mark these regions with face_bounded: true; normal
profile features, profile shapes, shading, hashing and picking use the
evaluated regions. An off-face placement or a new non-face plane leaves
out the boundary curves, and a reference requiring a lost boundary fails
as a missing profile. Boundary extraction requires a named edge or
unambiguous source-profile provenance. Missing provenance, distinct
references merged onto one edge, or a source split into ambiguous pieces
warns and retains only the sketch's own regions; no guessed piece number
is used. This does not exclude surface bodies whose boundaries have
usable references.
A profile feature's profiles are a set of these regions: the area they
select is the odd/even composition of the selected regions, which never
overlap, so each region once whatever the order or repetition of the list
(extrude::selected_regions, shared by preview and evaluation; references
that find the same region count once). Toggling a region is the
application's: a click on a selected region takes its entry out
(#199; commands.md, Profile
selections).
Solid mode's Autoselect groups come from the model's autoselect_profiles
query (document/autoselect.rs, #193). Only the final unused sketch
at the end of the timeline qualifies. Projected, drawn and hybrid groups
classify every boundary segment, including holes, by stored provenance:
Entity::reference covers unlinked projections too, independently of the
solver's fixed flag. A projected rectangle around drawn circles has a
hybrid surrounding region and separate drawn circle interiors. Region
keys come from the current evaluation, so edits and undo cannot leave
cached candidates. The application owns per-item toggles and hover
previews, and passes normal profile preselection to commands.
A linked projection that moved is solved as if dragged from where the
stored definition has it (project::solve_followed): the solver system is
built at the stored positions, where each constraint takes its orientation
choices (the side of a signed distance or tangency, an angle's quadrant),
and then moved to the followed positions to start the solve
(SketchDef::solve_oriented, solve::Extra::oriented; mitcad#1047). So
geometry constrained to the projection keeps the side it has in the stored
sketch whatever the size of the move; before, the sides came from the moved
start, and a point dimensioned 0.5 mm from a projected edge that moved
0.5 mm lay on the edge and took a side by chance. A large move is also
solved in steps (as the solver's continuation does for a dimension
change). The stored definition
keeps the positions of the last edit; the evaluation's moved entities
(SketchOutput::moved) are what the sketch query shows and what the
next edit starts from (and then stores).
Each entity of a linked projection follows the fresh curve of its kind most
like it (by points and sizes; in the kernel's order when that is as
good), so a projection of some of a face's edges, or of edges listed in
another order, follows; one that finds none, and a projection whose
source is gone, keeps its last geometry and is a warning on the sketch
(SketchOutput::follow, #232). Projecting leaves out curves the
same as another of the source; Clean Up Projections
(sketch/cleanup.rs) removes repeats across projections and lines on
another on request. The evaluation also lists, per projection that did not
follow, its stale curves (ProjectionFollow::stale: matching none of the
source's current curves); Clean Up Stale Projections (sketch/stale.rs,
#252) removes those nothing uses, trims stale lines to the regions
later features use (only when those keep their names and areas) and
unlinks the projections that still cannot follow; it never links one
again by geometry, as following would move its curves. Project Again
(sketch/again.rs, mitcad#1303) is the repair the user asks for: the
evaluation also keeps, per projection that did not follow, its source's
curves as they are now (ProjectionFollow::current), and the command
makes the projection anew from them, moving each old curve's constraints
and dimensions to the new curve of its kind that covers it once the old
outline is laid over the new one; new curves take the old ids, and what
does not map stays on the old curves, kept as construction references.
A projection that only moved or was resized follows without it: when the
nearest-first pairing would tear its arcs, the order of the lists or the
nearest once the outline's bounds are laid over the new ones is tried
(project.rs, aligned_pairs). So does one whose run of arcs of one
circle the source now lists as one arc of their sweep: when the pairing
leaves anything over, that arc is split as the projection's run is, at
the same angles (split_like, mitcad#1325).
A projection of one edge whose source was merged with, or split from,
edges on the same curve (mitcad#1784, sketch/successor.rs) follows the
edges on that carrier: for a lost source the model lists the edges
between the faces it lay between, as the shape names them now
(features/projection_successors.rs, through Kernel::edges and
Kernel::curves_of; no kernel method of its own), and for a name that now
finds pieces of nothing like its curve those pieces; they must lie on one
circle or one line of its curve's kind, and its used points must have one
place among them. It keeps its entities' kinds but one: an arc of what is
now one whole circle, nothing on its ends and nothing on it that needs an
arc, becomes that circle (mitcad#1794); the evaluated definition keeps the
arc's ends as loose points so that it pairs entity for entity with the
stored one, and project::with_moved (the sketch as it evaluated, which
queries show and edits start from) takes the kind change and leaves the
ends out. It says so as information (ProjectionFollow::successor), and
otherwise stays lost with the edges listed for Project Again
(ProjectionFollow::candidates, sketch.project_again with successor,
which the application's Project Again offers as a list, mitcad#1794). A 3D
sketch's kept projections follow the same way, and its linked reference
records take the one line or round edge between a gone edge's faces
(spatial_sketch.rs, successor_edge).
Two kinds of linked record share this machinery (#389): section
curves (Projection::section, sketch.project with section), where
the sketch's plane cuts a face, computed by the kernel
(Kernel::section_curves: each face cut by itself, B-spline pieces that
meet end to end joined into one), with the plane moved into the source
component's coordinates by the link; Intersect (mitcad#736) adds an
edge's crossing points with the plane (Kernel::section_points) and a
whole body's section, one section record per face its pieces lie on
(sketch::project::section_groups); and a projection of a chain of edges
(Projection::chain, made by the .f3d import for a curve the model
splits into pieces, a thread's helix of an edge per turn), the edges'
curves joined end to end into one B-spline in the model
(sketch::project::join_curves) before they are projected.
Editing operations (trim, extend, offset, mirror, patterns, project, move/copy, fillet, chamfer, slots, polygons) are model commands producing entities and constraints, shared by the UI and the imports.
- Text (
sketch/text.rs): glyph outlines fromKernel::font_glyphs(OCCT font manager; bundled Droid Sans as fallback), laid out in Rust; each outline is a region curvet<n>.g<k>.c<j>. A text may carry the outlines a file stores for it (glyphs, mitcad#416), laid out instead of the fallback font's while its font is missing and its string and font are unchanged. Font files and shaping (mitcad#473,sketch/fonts.rs): a text's font may come from a file the model reads itself (skrifa; WOFF and WOFF2 decoded by wuff), its outlines stored with the text. Only a file chosen in the session is read again (FontFile::chosen, not saved, mitcad#929): a path that came with a design needs the stored outlines, so a design file never makes the model read a file it names; text in a font file, and right-to-left or joined scripts in an installed font (its file throughKernel::font_source), is shaped by harfrust in runs of one direction (unicode-bidi), the C++ side giving only the installed fonts' outlines and files; every line is laid out in its visual order. QR codes (sketch/code.rs) are texts whosecodeturns their content into module contours. - SVG drawings (
sketch/svg.rs, mitcad#473): read with roxmltree and svgtypes into exact sketch geometry (lines, Bézier splines, circular or elliptical arcs), texts as sketch texts, the regions a drawing fills found by its fill rules after the insert. - Patterns (
sketch/pattern.rs): copies are tied to originals by solver constraints (Translated,Rotated,TurnedDirection,EqualSize), so they add no DOF and keep ids when the count changes. - Offsets (
sketch/offset.rs): lines, arcs and circles are offset exactly with constraints. Chains with ellipses or splines are derived after each solve as a C1 cubic B-spline within 1e-4 mm; they are not solver unknowns, and dragging them moves the source chain. Corners: Round (mitcad#1774,SketchOffset::round) puts an arc about the source's corner at each outer corner of an exact offset where lines or arcs meet at an angle (mitcad#1786), held tangent by the offset's own bindings. - Equal spacing (
sketch/spacing.rs, #221): one constraint on independent objects' anchors (points, circle and arc centres, line midpoints) in a stored order; the solver'sEqualSpacingmakes each successive interval (x, y, along a line, or a distance) equal to the next, and an optionalspacingdimension (Spacing, on the first interval) drives them all. No copies, no alignment, no sizes bound. - Copy and paste (
sketch/clipboard.rs, mitcad#788): a fragment is plain data (entities, texts, constraints and dimensions with the source's ids, values with the expressions and parameter names they use, and the ids that stood for the origin and axes), so it goes between sketches and designs through the clipboard; a paste maps every id anew and the origin and axes to the target's own.
The solver works on its own ids; the sketch model maps entity ids to them.
3D sketches (mitcad#1501, first stage mitcad#1520) get a solver system of
their own, separate from the planar one: mitcad_solver::SpatialSystem
(core/solver/src/spatial.rs) with three coordinates per point in the
sketch's local frame, lines that refer to their end point ids (shared
identity) and explicit coincidence, fix, target attachment, axis
alignment with a sense, signed axis offsets and true lengths, all as
millimetre residuals on the planar solver's iteration, drag, sparse
factorization and rank analysis. It accepts a solve at an absolute
1e-6 mm, refuses collapsed lines (SPATIAL_MIN_SEGMENT) and aligned
lines pointing against their sense, tells conflicts from singular rows
and non-convergence, and restores every point when a solve or drag
fails. The frame and source vertices are the caller's (a vertex becomes
a local attachment target); the spatial sketch feature, its commands and
the Qt editor are later stages, so nothing in the model uses it yet
(solver README).
mitcad#1542 adds arcs (a free unit normal or a plane-bound frame axis),
circles, control-point and fit-point splines (the planar spline basis,
generalized to three coordinates), constant reference curves (source
edges) and their relations: point on curve with a bounded parameter,
midpoints, tangency with a validated sense, equal, radius, diameter, arc
length, normal alignment and sketch-plane membership. A converted
sketch's planar relations are compiled by the planar row compilation
(prepare::compile_mapped, extracted from prepare) onto the spatial
x and y columns through a shadow planar system.
The 3D sketch feature (spatial_sketch, mitcad#1521) is the solver's
user in the model. Its definition, the adapter to SpatialSystem and the
evaluated output are in core/sketch/src/spatial.rs
(SpatialSketchDef), its edits in core/sketch/src/spatial_edit.rs
(SpatialEdit); the model evaluates it in
core/model/src/features/spatial_sketch.rs and edits it in
core/model/src/document/spatial_sketches.rs. Planar sketches, their
regions and commands are unchanged.
- Definition: a support (an origin plane, a construction plane or a
planar face of the sketch's component, found as a planar sketch finds
its plane), points
p<n>with three local coordinates (the last solved positions, the next solve's start: never a relation), curvesc<n>by the points that define them (SpatialCurveKind: lines, arcs with a stored unit normal that is free or bound to a frame axis, circles, control-point and fit-point splines whose hidden control points are the solver's, plane-bound ellipses and elliptical arcs kept from a converted planar sketch, and reference curves whose constant geometry is supplied when the sketch is built,SpatialInputs), textst<n>kept from a converted sketch, relationsk<n>(coincident, fix, attach, align with an axis and a sense, point on curve, midpoint, tangency with the sense it was made with, equal, normal alignment, On Sketch Plane with one representative per elevation group, and in-plane planar constraints and fixed entities of a converted sketch, mapped by the planar sketch's ownsolve::planar_constraint) and dimensionsk<n>(true length, signed axis offset, radius, diameter, arc length, spline length (driven only), in-plane planar dimensions; driving with a parameter, or driven and measured only, without a parameter, so no measured value drives its own sketch). Linked reference records (mitcad#1543) follow their sources: an attachment (Attach, to a source point) and a reference curve (one per source and occurrence, reused by every point put on it with a Point on Curve or Midpoint relation), each with aSpatialSource(the origin, a vertex, an edge, an edge's start, end or middle, another sketch's point or curve, planar or 3D, an Intersection Curve's curve, or a point of such a curve; with anOccurrenceLinkfor another component's geometry, as a planar projection's) and a mode: included in true 3D, or projected along the sketch's normal onto its plane (projected, throughproject.rsas a planar sketch's Project). A point on a face of a body (mitcad#1549) is an On Face relation with aSpatialSource::Face(body, face name, link), the face's record: before each solve the face is found by its name (in another component through the link), the kernel'sface_geometrygives its surface, and a plane, cylinder, cone, sphere or torus becomes aSpatialSurfacein the local frame, solved in closed form (one row, the signed distance); any other surface is solved through the kernel'sface_point_normal(closest-point projection): the point lies on the plane touching the face at its projection, andsolve_on_facessolves again from the projection of the solved point until it lies on the face (16 rounds, 1e-6 mm; a drag between solves uses the last touching plane, the evaluation that takes it puts the point back on the face). No new kernel methods; the mock kernel'sprojected_facesstands in for a free-form face. A plane-bound ellipse (mitcad#1550) is a curve of the solver (SpatialSystem::add_ellipse): its centre, its major point in the plane through the centre square to a frame axis, a minor radius column solved like a circle's radius, an elliptical arc's ends held on it (OnEllipserows),PointOnand theEllipseRadiusdimensions; in-plane relations take a full ellipse. In-plane relations have a plane (mitcad#1550): the shadow keeps one planar stand-in of a point, line or curve per frame plane, on that plane's two coordinate columns (spatial/plane.rs), so a rectangle or polygon drawn on the YZ or ZX plane keeps the planar tools' relations there; its points are held in the plane by aplane_boundrelation (offset rows along the axis). The plane-bound drawing tools of the app (sketch/Sketch3dShapes.cpp) sendsketch3d.add_circlewithplane,add_ellipse,add_rectangle,add_polygonandadd_text; texts are laid out by the planar layout in their plane at query time (SpatialSketchDef::text_outlines). - Evaluation: the support's frame made orthonormal (
O,R), every record's source found in one place (source_geometry: a vertex or edge by its topological name, renamed by a sketch change found again when that is unambiguous, never replaced by a nearby point, a name of several edges refused; another sketch's entity from its output; another component's geometry in its component, moved by the link's placements) and moved into the frame (R^T (V - O); an attachment's target the source point or the start, end or middle of the source curve,local_source_point; a reference curve bylocal_reference_curve), then one solve. A lost source fails the sketch as a reference failure: no silent detach, no last geometry kept. The checks before the solve refuse sources that do not come before the sketch, and name a later source that uses the sketch as a link cycle. A 3D sketch's points and curves are themselves sources: of later 3D sketches and of planar sketches' Project (sketch_entity_geometry, read as the 3D sketch's output). Reads are recorded as for any feature, so a moved support or source evaluates the sketch again and the frame is applied once. A failure (support, reference, value, conflict, no convergence, invalid geometry:SpatialFailure) fails the feature and keeps its definition; the output (Output::spatial,Document::spatial_sketch) then has the frame and the failure but no geometry. A solved output maps each curve once to aCurve3in the component: a line, an arc as a conic (major = minor = radius,x_axistoward its start,normalits normal, from 0 to its sweep), a circle as a closed conic, a spline as a B-spline (a fit-point spline by its solved control net), a plane-bound ellipse as a conic. A solved 3D sketch's output also has a planarSketchOutputof its sketch plane (mitcad#1550,core/sketch/src/spatial_planar.rs,planar_view): its points, curves and texts within 1e-6 mm of the plane as a planar sketch with the same ids, whose closed loops bound profile regions under the keys a planar sketch's same curves have (with the supporting face's edges, texts and derived offsets); profile features take it throughCheckContext::profile_sketch, andDocument::profileslists it. - Edits:
Document::edit_spatial_sketchruns aSpatialEditon a copy of the whole state (definition, parameters, ids), evaluates the copy up to and with the sketch, and takes it as one undo step only when the sketch solves, storing the solved positions; anything else changes nothing and returns the failure with its relations and entities (SpatialEditError). A route segment with its new end point, attachments, axis and dimensions is one such edit, and so is an arc (Three-Point, Centre or Tangent, with its new centre and end, radius and arc length) or a spline with its new points; the solved normals, radii and tangency senses are stored with the positions. Drags pull points with temporary soft goals (preview_spatial_dragchanges nothing,drag_spatial_sketchis one undo step). Before a solve or a drag the fit-point splines' hidden control points are fitted to their fit points with the fit points held (temporary Fix rows): made by natural-end interpolation at each build, they would otherwise pull free fit points along when a tangency takes an end (mitcad#1522). - API and files (mitcad#1522,
core/model-api/src/sketch3d.rs): thesketch3d.*command family (its ownCommandFamilywith the prefixsketch3d.) and thesketch3dquery, classified as the model's own so MCP permits them; each command is oneedit_spatial_sketchand returns the ids it made. Points are[x, y, z]or point ids; the planarsketch.*commands, thesketchquery and the clipboard refuse a 3D sketch by name instead of reading its points as planar ones. The design file stores the definition under the feature typespatial_sketch(FeatureDefserialization, no new file version); a reader without the type refuses the design withunknown variant. Linked references (mitcad#1543) addsketch3d.attach,sketch3d.includeandsketch3d.replace_reference, extendsketch3d.detachto Point on Curve relations with reference curves, take another component's source with theoccurrencethat shows it (made into the record's link), and list the records in the query'sreferences. A face source ({"body", "face"}, mitcad#1549) makessketch3d.attach(and the sources ofadd_point,add_lineandadd_arc) add anon_facerelation, listed withkindface; Replace Reference keeps it a face. - Paths (mitcad#1523,
core/model/src/features/spatial_path.rs): a Pipe or Sweep runs along curves of a 3D sketch through the typed pathSpatialPath({"spatial_sketch", "curves", "reversed", "chain"}), a third form of the sweep family'sCurvePathbeside the planar sketch curves andPathRef. It is not baked into fixed curves: every recompute reads the sketch's output (a recorded read) and the definition's joints. The order comes from topology, not positions (route): curves join at shared points and at points made coincident (union of Coincident relations, and of a converted sketch's in-plane point coincidences, whose ends are then checked to meet); a node where three or more picked curves meet is a branch, a loop is a closed path (mitcad#1550: from the first listed curve round to it again; a curve without ends is one by itself), and ends that only lie close never join. The path runs through its first listed curve along that curve's own direction (against it whenreversed), andpiecestakes each curve'sCurve3from the output once, turned round bycurves::reversedwhere the path runs against it, so the planarchain's geometric joining is not used. The check before evaluation covers only the selection (ids, kinds, a 3D sketch of the component before the feature), so a sketch edit that breaks a chain is taken and fails the consumer; a failed sketch fails it with no last geometry.chainslists what chain selection finds (thesketch3dquery'schains), andpath::spatial_rewrite/rewrite_spatial_pathsturn a planar path into the typed one with the same ids and direction for the in-place conversion (mitcad#1544), for every path a feature holds (path::for_each_path). Every curve input takes it (mitcad#1550): a loft's centre line and rails areCurvePaths;PathRef::Spatialis the same typed form for path patterns and the construction features along a path, resolved throughResolver::spatial_pathand measured as an Intersection Curve is (CurveChain); axis, line and point references (GeomRef::SketchCurves,SketchPoint) naming a 3D sketch resolve throughResolver::spatial_entity; Intersection Curve, boundary surfaces and surface lofts take a 3D sketch's curves as a set (SketchCurves::check_anyandcurves,spatial_path::curve_set). Inputs that grow from their sketch's plane (ribs, webs, thin walls, surface sweeps of curves) take a 3D sketch's curves in its sketch plane in the planar form (SketchCurves::check_in_planeandin_plane): the planar output of its sketch plane, which also bounds its profiles, has them under their ids, andcurves_onrefuses a curve it lacks, naming the sketch (mitcad#1550). Tools of sketch curves keep planar sketches, and a path's planar form naming a 3D sketch is refused (not_spatial). - Editing context (mitcad#1524, app/COMMANDS.md "3D sketches"): the
shared Qt UI only. Create Sketch asks for the kind (2D or 3D) before the
plane and sends
sketch3d.create; Edit Sketch of aspatial_sketchenters sketch mode withsketch::Sketch3dControllerin place of the planarSketchController, which stays inactive. The controller reads thesketch3dquery (Sketch3dModel) after each change; the view draws the points and curves through its sketch display (spatialSketchEntities: local coordinates mapped by the frame, the occurrence's placement applied once), so picks and highlights carry the stable point and curve ids; reference curves come with their geometry in the query (geometry.kindline, conic, bspline or helix). The overlay adds the frame, control polygons, tangent handles,In planebadges (one per shape: the points joined by curves and in-plane relations, mitcad#1592) and the hover, every badge kept inside the view's uncovered area; the 3D Sketch Palette the status. Leaving a 3D sketch keeps the camera (OcctViewer::keepCamera), also for one converted from 2D; leaving a 2D sketch restores it. The 2D tools and profile features are disabled with a reason; Finish Sketch, undo and a rolled-back Timeline are sketch mode's for either kind. The timeline gives a 3D sketch'sdof, and it has a light bulb of its own (set_feature_visible). - Drawing tools (mitcad#1525, app/COMMANDS.md "3D sketch drawing
tools"): the SKETCH tab's Point, Line, arcs and splines start the
controller's own tools in a 3D sketch. What is placed, snapped and typed
is the editor's state only (
Sketch3dDraw.hpp: plain geometry, unit tested; the temporary plane, the anchor and a pending point are never stored). A curve commits as itssketch3d.add_*command with what the command takes (point ids, sources, offsets, axis, length, radius, arc length, Keep Plane's normal axis), and what it does not (an attachment of a spline point or an arc's centre, a relation with this sketch's own curve, an offset typed for an arc's or a spline's point) follows as further commands merged into one undo step (merge_undo); a refused follow-up undoes the step's commands, so nothing of it stays. No model command was added for the tools. - Editing (mitcad#1526, app/COMMANDS.md "3D sketch editing"): the
relations and dimensions a selection takes, their list, Fix, Detach,
Attach, Replace Reference and Delete send the existing
sketch3d.*commands (Sketch3dEdit.hpp, plain and unit tested). A drag of a point, a curve or a fit-point spline's tangent handle previewssketch3d.dragwithpreviewon every move and commits it once on release; the drag plane is the editor's only. The one model addition is the tangent handle:sketch3d.drag'stangentsare soft goals on the hidden control point next to an end (the solver'sdrag_with), and an open fit-point spline stores the end tangents of its free and tangent ends (tangents), which the next solve starts from, since the interpolation that seeds its hidden control points has natural ends. - Conversion in place (mitcad#1544, commands.md "Turning a planar
sketch into a 3D sketch"):
core/sketch/src/spatial_convert.rsmaps a planarSketchDefto aSpatialSketchDefwithout the document (ids kept; the planar sketch's own frame kept as the 3D sketch'sframein its support; Coincident of two points a 3D coincidence, fixed entities in-plane fixes, every other constraint and dimension an in-plane one through #1542's adapter; one On Sketch Plane row per elevation group that nothing else holds, so DOF and redundancy are the planar sketch's; linked projections as projected attachments and reference curves).Document::convert_sketch_to_spatial(document/sketch_conversion.rs) puts it in the feature's place in a copied state, rewrites later paths withrewrite_spatial_paths, checks every later feature against the 3D sketch (naming each one in the way), matches projected line ends to their sources' ends from a probe evaluation, solves it, and takes it as one undo step only when no evaluated feature fails that did not. An in-plane dimension's value slot is its planar one's (dimensions[k5].angle), so its parameter keeps its unit. The app switches editors (switchSketchEditor) within the same sketch edit, and back on Undo (followSketchKind). What 3D sketches have no own form for (mitcad#1550) is kept in the definition'splanarrecords (PlanarRecords): patterns and offsets bind in the plane as in-plane solver rows (SpatialSketchDef::in_plane_bindings, the planarpattern.bindings,offset::tangent_cornersandoffset::independentthroughsolve::planar_binding), derived offsets' curves are planar only and made again in the planar view, the placement and a plane of another component make the frame, text parameters fill the texts, inactive items are skipped by the build, and linked projections that no reference record can stand for keep their planar records, followed (project::follow_linkson a planar shell) before each solve with their entities held by in-plane fixes. Back to 2D,spatial_planar::planar_from_spatialmaps a 3D sketch that all lies in its plane to a planarSketchDef(in-plane items and records back, 3D relations as planar equivalents, attachments and reference curves as linked projections whose curves a probe evaluation finds) andDocument::convert_sketch_to_planarrewrites later paths (path::for_each_path) and checks the features after it as one undo step. - Fillet (mitcad#1548, app/COMMANDS.md "3D sketch Fillet"): the model
edit
SpatialEdit::fillets(sketch3d.fillet) rounds corners of lines with relations of the existing kinds only, no new solver row: the lines are trimmed to new tangent points keeping their ids, the arc gets two Tangent relations and a radius dimension, and the corner point stays where the lines' extensions meet through two construction lines to it, the first Tangent to the first line (collinear) and both Equal. That holds the corner with no redundant row: a Tangent of the second line to its construction line as well would tie the lines' common plane twice, which the arc's tangencies already fix. A line's Length, Equal, Point On Curve and Midpoint move to a construction line from its other end to the corner, so they keep measuring to it. The edit report'sroundedletsedit_spatial_sketchadd each arc, in the same undo step, to a Pipe's or Sweep's path that lists both of its lines (path::take_fillet_arcs). The Qt tool (Sketch3dFilletTool.cpp, the plain geometry inSketch3dFillet.hpp) sends one command per corner, with a typed radius as typed or a dragged one along the bisector in millimetres. - Path selection (mitcad#1527, app/COMMANDS.md "Pipe and Sweep along
3D sketches"): the Pipe and Sweep panels keep their inputs; a pick of a
3D sketch's curves (
SketchCurveitems of the sketch, as the view draws them) is written as the typedSpatialPathbycmd::pathOfwith the context, and read back bypathItems; a Loft's rails and centre line are written so too, so that the model refuses them in its own words. A whole 3D sketch (its Browser row or timeline entry) stands for its one open route, from the query'schains. The panel lists a pick's route from thesketch3dquery'sroute(spatial_path::routeon the definition, the joints deciding as in the recompute), so the app does not order curves itself;commands/SpatialPaths.hpp(plain, unit tested) holds the JSON forms. The direction is the model's: the first listed curve andreversed, which an edit keeps (Pipe's Reverse shows it). The timeline'ssketchesof a feature include the 3D sketches it uses (the Browser lists a Pipe under its route; its edit shows the route), while a used 3D sketch is not hidden (used_sketchesstays planar). The planar sketch-curve forms naming a 3D sketch outside Pipe, Sweep and Loft are refused bypath::not_spatial.
Formula assistance lives in the Rust expression layer: its existing tokenizer
and AST provide partial-call signatures, source ranges, lexical LET context
and sub-expression evaluation through the read-only formula_help query.
The Qt FormulaEditor shares this query with value fields and returns ordinary
formula text and normal parameter-limit edits; it stores no additional design
state. Both the fx browser and Edit Parameters open the same editor.
The app uses the model only through JSON commands and queries
(commands.md); geometry comes back as
SharedPtr<Shape> handles, so new commands need no bridge changes.
A preview computes on a copy and leaves results in the cache, so OK does
not recompute.
- Commands (app/COMMANDS.md): a UI command is a
declarative definition; the framework builds the panel, selections,
preview and add/edit. Editing rolls back to before the feature,
previews there, and on OK runs
edit_featureas one undo step. The joints, rigid groups and other features that only place occurrences right after the edited one are previewed with it (edit_feature'sthrough, mitcad#1860), and a preview that cannot be shown while a value is typed, or an edit's that fails after one that placed occurrences, leaves the last good one drawn, so an assembly does not come apart in the view while it is edited. A feature's preview draws the design as the view shows it with the command's result (app/framework/PreviewBodies.hpp, #266): shown bodies keep their occurrences' placements, what the command makes comes at the placements the report'sinstancesgive, and a body the view hides stays hidden. A body the command consumes as a tool stays drawn, see-through and pickable, where other occurrences show it while its input is active (InputDef::toolOverlays, mitcad#561). - Viewport picks (
app/PickContext.*): nearby edges and vertices precede the face or edge they bound. Selection overlays resolve to the original body's local topology and exact occurrence before this ranking, so selected faces leave their edges available while remaining pickable for removal. While a command's preview shows the body changed, an overlay hit no farther than the preview's first hit ranks before the preview's items (setPickCovers), so a face of the same name on the preview does not take the click meant for the selected face or its edges (mitcad#672). Opposing edges of a narrow face win only where one is clearly nearer the cursor; hover and clicks use the same ordering. The pick places UI tests click (OcctViewer::pickPoints) are the camera's projection rounded to the nearest logical pixel, probed at exactly that pixel. - Sketch mode (
app/sketch/): the app keeps the sketch in the form of thesketchquery and does snapping, inference and hit testing itself; every change is asketch.*command, one undo step per user action. Drawing tools turn typed sizes into driving dimensions in that same step; a polygon's typed radius dimensions the construction circle it measures, and Edge Polygon's typed length dimensions the clicked edge. A polygon's side count is its geometry, not a dimension. Tools use a custom cursor (app/framework/Cursors). Body edges and vertices in the sketch plane, which the Dimension tool picks and the Point tool snaps to, come from the model'splane_geometryquery (the coplanarity test is the model's, on the kernel's curves); they are projected, linked, only by the action that makes something from them (#256, #258). The same query without_of_planealso gives the other edges and vertices, as what they project to along the plane's normal and with where they are, so that the Dimension tool picks them where the view shows them and projects them the same way (mitcad#866). The application reads them again only when the model'splane_geometry_keychanges (the sketch's frame and the bodies before it), not after each edit of the sketch itself (mitcad#1646), and the items out of the plane off the UI thread, as a model job of their own that gives way to the user's next action (mitcad#1656). A component's sketch is edited where one of its occurrences shows it (mitcad#505): thesketchquery's frame is in the component's coordinates, and sketch mode places it in the design by that occurrence once (SketchHost::sketchPlacement): the plane link's target for a plane of another component, else the occurrence its face was picked at, else the component's first. The view's sketch plane, Look At, the grid, Hide Above Sketch and the sketch's curves and profiles all use that one placement; outside sketch mode a component's sketch is shown at its component's first occurrence. During a geometry drag, the edited sketch's filled profiles are removed from display and picking; curves and points stay live. Profile queries and face rebuilding wait until release or interruption, including a drag the solver refused. Dimension-text drags keep their profiles. A sketch on a cylindrical or conical face (mitcad#1768,sketch/SketchSurface) keeps all of this in the face's developed coordinates: only the view's picture of it lies on the face. Points, highlights and previews go onto the face by the model's own map (thesketchquery'ssurface), its curves are thesketch_surfacequery's polylines, its profiles the flat regions laid onto the face as triangles, its dimensions' lines bent onto the face by the same map (mitcad#1853), the layout grid not drawn (its layer lies under the bodies), and the pointer comes back into the sketch through the same query's rays, so the app never inverts the map itself. - Navigation settings (
app/view/Navigation.hpp): stable preset ids share a canonical input table with Custom bindings. Reserved selection drags and the orientation cube remain separate. The viewer applies orbit acceleration through OCCT, scales pan deltas with fractional carry, and scales wheel/drag zoom; a drag zoom follows the vertical motion only, up zooming in (OCCT's vertical zoom gesture, turned for a drag's steps inOcctViewer::UpdateZoom, mitcad#1867); trackpad scrolling has its own multiplier. Settings and the visual guide use the same binding table. - 3D mice (mitcad#951):
app/platform/SpaceMouseDevice.hppis the small backend interface (six axes in the view's frame, button events, hot plug) with the pure parsing of the devices' reports; one backend per platform, none with a vendor SDK: Raw Input on Windows (platform/windows/SpaceMouseWindows.cpp), spacenavd's own socket on Linux and the BSDs (platform/unix/SpaceMouseSpnav.cpp), IOKit's HID Manager on macOS (platform/macos/SpaceMouseMac.cpp). A missing device or daemon is no error.view/SpaceMouseControllermaps the axes to the camera's rates (view/SpaceMouseNavigation.hpp: speed, dead zone, reversed axes, locks, the dominant axis held until the cap is at rest, the cross-talk filter and the device's reach of mitcad#1720, kept in the controller'sSpaceMouseMemory; pan and zoom only in sketch mode) and runs the buttons' view commands through their actions;OcctViewermoves the camera by the rates at each frame in the 3D mouse's Navigation mode (mitcad#978: Object and Camera about the mouse orbit's centre,AIS_ViewController::GravityPoint, the one opposite to the other; Fly about the eye in perspective) and with its own Lock horizon, not the mouse's Constrained orbit. The settings are part ofNavigationSettings. - Timeline inspection (
app/browser/FeaturePresentation.hpp): hover previews are independent of selection and exclude failed, suppressed and rolled-back features. A nonpickable dashed boundary on the Topmost layer locates enclosed geometry alongside the normal shaded highlight. Tooltips and feature cards share command labels, loaded dimension text and component names; they do not expose internal identifiers. - Browser, timeline, view (
app/browser/,app/view/): the model is read once per change; the view keeps AIS objects that did not change. Visibility is the model's: an unset sketch light bulb follows "hidden while a feature uses it" (document/browser.rs). The browser lists each feature under the sketches it uses (thetimelinequery'ssketches, from the same references), and its selection and the timeline's follow each other (#177). The light bulbs of bodies, sketches, construction geometry, components and their folders work in every mode, and so do a kept analysis's and an image reference's (mitcad#1263: a section turned on clips the open command's preview, which no longer covers the cut and is computed again); during a command they run outside its undo range (a cancelled command leaves them, a committed one is an undo step of its own after them;CommandSession::runVisibility, #295). Edit Parameters works the same way while a panel is open (CommandSession::runParameter, mitcad#564): the panel's values are evaluated again and its preview computed again, and an edited feature's own parameters stay the panel's; in sketch mode a change is a sketch action's undo step and the sketch is read again. Create Sketch shows the origin planes for its pick in every design, behind the model's faces for picking, without touching the Origin folder's light bulb (mitcad#844, replacing #294); a command's input that takes construction geometry shows the origin only as the light bulb does, its rows in the browser picked instead (mitcad#1030). A command shows the sketches it uses for its time, as if their light bulbs were on (an edited feature'ssketches, a new command's starting profiles; a view state of the window,view/CommandSketches.hpp, never a model command: mitcad#546). In the native macOS Browser, Return/Enter activates the selected row before document confirmation; a row's text editor keeps Return while renaming. Command-W dismisses command and timeline search popovers, preserving the document and restoring timeline search's saved selection. - Background computation (
app/framework/ModelWorker): the model runs on one long-lived worker thread (256 MB stack, OCCT crash handlers) as jobs, one at a time; opening, every model command, undo/redo and every panel preview is a job. The document belongs to one thread at a time. The view keeps drawing what it built earlier but must not read or triangulate shapes while a job runs (OCCT writes flags and triangulations into shared sub-shapes). Explicit Qt commands stay synchronous: 50 ms blocked, then input queued, after 400 ms a modal progress dialog whose Cancel goes to the job'sRecomputeMonitor(JobControlin the bridge). The memory guard of model commands (mitcad#1480,core/ffi/src/command_memory.rsovermitcad_model::monitor::memory_guard) measures the process every 0.02 s while a model command (not an import, undo or redo) computes and, at 85 % of its tightest memory limit, when the memory grows so fast that it would get there within 0.1 s (a boolean's threads can add gigabytes a second, mitcad#1493), or after a failed allocation in the kernel, cancels the same monitor with its reason (cancel_because): the command fails with "the operation ran out of memory …" and changes nothing, and the job counts as failed, not cancelled (JobControl::cancel_reason). The application, the headless MCP server (--memory-limitfor a lower limit) andmitcad-cli info/runturn it on (guard_command_memory); the imports keep their own guard (#80,mitcad_import_base::memory_guard), which measures as often and looks ahead with the same code (MemoryGrowth,low_ahead; mitcad#1505), only from 50 % of the limit and at growth kept up over two measurements, and cuts the definition being evaluated short instead of failing the import. The wait cursor is a guard of the wait (app/framework/WaitCursor, #268): restored once, by the dialog or at the end, logged; one left on is cleared when the window is idle. Hover, clicks and candidate-point enumeration all suspend while a job owns the document; candidate probes also call model-backed command filters. Queries run on the UI thread between jobs; reads during a job are refused (ModelBusy), and deferred work waits for idle (MainWindow::whenIdle). What the UI must know at once during a job it takes from what it showed last instead: the length unit a value box gives a typed number when Enter closes it while a preview computes (MainWindow::lengthUnit, from the snapshot, mitcad#888), whether the design is modified (the title's mark). A job's wait runs the timers (a synchronous command's event loop, an asynchronous preview's), so a call put off "until after this event" that reads or changes the model goes throughafterEventWhenIdle(app/framework/IdleCall.hpp): at once when no job runs, else at the job's end; a change of the edit lock waits so too.MITCAD_COMPUTE_INLINE=1runs jobs on the UI thread for debugging. Feature previews use asynchronous jobs on both frontends (mitcad#634), without modal progress. So does Send to Slicer's bed plan while its panel is open (mitcad#1121:DocumentSession::commandTaskAsync, the jobbed plan): keys typed into the opening panel stay the panel's, and its Send waits for the plan (CommandDef::okWhileBusy). The first pending input starts a bounded 150 ms timer; further input does not restart it. While a job owns the document, numeric edits replace one pending action per field, evaluated only on idle. Structural edits form ordering barriers and invalidate/cancel old work; a typed (or stepped) value cancels a feature preview that has computed for two seconds or more (mitcad#1788), a quicker one and a drag's are kept. A completed numeric preview may display intermediate geometry, but only the latest input's result may update operation/target controls or enable OK. Pending values drain before the next job, without another debounce delay; a value of the same field taken at once (the model idle before the drain) empties them, so none puts an older value back (mitcad#636); release requests an immediate preview and OK waits for the latest exact result.MITCAD_LOG_TIMING=1also logs numeric queue replacement/drain counts and solid installation during a drag.ManipulatorOverlaykeeps a separate continuous pointer value for local drawing (mitcad#637). Its snapped value alone emits a command input change; the marked snap position and field remain the committed value. An unchanged snap interval updates only the overlay, including while the worker is busy. A form refresh preserves pointer feedback for the same handle geometry; a changed placement/kind or a removed handle invalidates its grab. Opt-in feedback counters distinguish delivered moves, semantic changes, visual updates and overlay paints. The jobs that change what the view draws (opening, model commands but a sketch's own, previews) end with the view's meshes of the shown bodies, the previewed ones and the tool (app/framework/DisplayMeshes, #398): made on the worker as the view makes them, so that the view only finds and keeps them, and a design of large curved faces keeps the window (and live MCP, which then answers busy) responsive; the job's Cancel stops that meshing only, and the view meshes what is left. A face whose triangulation does not end does not hold the Cancel (mitcad#846): with a job's stop, the faces are triangulated on the meshing's own detached threads, each on a private copy of its face whose triangulation is moved into the face when it ends; once stopped, the meshing waitsio::kMeshAbandonSeconds(2 s) for the faces under way and then abandons the rest, whose results are discarded whenever they end (MeshReport::abandoned). The bodies are then drawn with the faces meshed by then, and the view never meshes them itself. Such a face's thread counts inio::abandoned_faces()until it ends; a process that quits meanwhile (the application once its window and session are gone,mitcad-cli,mitcad-geomtool) ends withstd::_Exit, as for the imports' given-up tries (mitcad#936,app/framework/ProcessEnd). A face whose triangulation throws, whatever the exception, is left failed and the others are meshed; an allocation that failed in one makes the meshing throw "triangulation: out of memory" (mitcad#936). All the bodies of a job are meshed together, in one compound per deviation they mesh with (by their sizes, mitcad#1275: few steps, so few compounds) (io::mesh_all_in_place, mitcad#438), so that OCCT meshes the faces of all of them in parallel on every core (one body at a time, a design of many small bodies used a core or two) and a face that bodies share is meshed once; should that throw, the bodies are meshed one by one and one OCCT fails on is left to the view. Two tiers (mitcad#635): a preview's bodies are drawn through stand-ins, copies sharing no face, edge or vertex with them (geometry::independent_copy), meshed in the interactive tier (previewMeshOptions: the view's deviation, planes through OCCT's Delabella base triangulation, about ten times faster on planes with many holes for the same nodes); the bodies themselves keep no triangulation until a job meshes them in the final tier: the command that commits the preview, or a refinement job (no model change, no undo step) once a drag ends and the inputs rest, and opening a design (viewMeshOptions: planes by the default insertion; mitcad#644's checked Delabella,checkedPlaneMeshOptions, where a plane Delabella leaves without a triangulation or whose triangles' area is off its boundary's is triangulated again by the default, was the final tier until a design hung in it, mitcad#846). So a committed body never keeps a preview's meshes, and no job writes into a shape the view draws. Both tiers first take the triangulations of the faces a command or preview left untouched from the bodies as shown (io::reuse_triangulations: the same surface, curves, parameter curves, ranges and end points; nothing cached between jobs), so only the changed faces are meshed. A copied triangulation's nodes are moved into the new face's frame (a prism's top is its base's face placed by the face's location, a boolean's rebuilt top by its surface's, mitcad#1243), and a copy that does not then lie on the face (io::triangulation_on_face) is not taken: the face is meshed. Opening a design with the result store (meshOpenedForDisplay, mitcad#858) first gives each shown body whose shape's version has display triangulations stored with the final tier's options its faces' triangulations and edge polygons back (io::restore_triangulations, every face checked against the stored one before anything is written), so a warm open meshes no face; the bodies meshed instead go to the store once meshed to the end (io::triangulation_bytes). A changed body, other options or another build of the program find none (MITCAD_DISPLAY_MESH_STORE=0: never). The open does not wait for that write (mitcad#880; a large design's 600 MB took 11 s of its first open): its job only takes the bodies' triangulations and edge polygons by their handles (io::capture_triangulations, which later meshings, changes and the document's close leave as they were) with the bodies' versions (Document::display_mesh_write), and the window's writer (DisplayMeshWrites) turns them into bytes and stores them on a thread of its own after the open, a body at a time, each file whole or not at all. The design opened again waits for what is still queued for it; clearing the store or quitting drops what is queued (the next open meshes and stores those bodies again).MITCAD_DISPLAY_MESH_WRITER=0stores them in the open's job as before. A cold open meshes bodies while its recompute still goes on (mitcad#881,RecomputeMeshing; a large design meshed 23 s after a 12 s recompute that used one core). The open's recompute puts each shown body into a feed once no later feature can change it (Document::feed_final_bodies,core/model/src/recompute/final_bodies.rs): every feature is classified by its definition as changing no body (sketches, construction geometry, joints and the other features that only place occurrences or write parameters), the bodies it names (participants, a fillet's or chamfer's body, a combine's target and tools, the bodies of a move, transfer or pattern, what the features a pattern repeats change), every body of its component (an operation on all bodies, any other feature) or any body (a cut across components, a feature that made a component); a body is final after the last feature that may change it, and bodies a feature makes are new. A body whose display meshes the store keeps is left to the store. A thread of the open meshes what comes in batches, each body through a copy that shares no sub-shape with it (geometry::independent_copy; the body may still be read by later features, which a triangulation in its faces would change), and hands the copies' triangulations over by their handles (io::capture_triangulations). After the recompute no batch begins; the open meshes the other bodies while the last batch goes on, and the model thread alone then gives each body whose shape is still the one meshed its copy's triangulations and edge polygons (io::restore_triangulationsof a capture, checked face by face). A body changed after all, a batch cut short and the bodies not taken are meshed as before; the triangles are the same. The open's summary line counts the bodies meshed during the recompute, the time and the part after it.MITCAD_MESH_DURING_RECOMPUTE=0turns it off. A body meshed to the end by a job or given its stored meshes is drawn with them as they are: its drawers do not mesh (drawerMeshes, mitcad#878), where they ran OCCT's mesher over a body again on the UI thread whenever a face's deviation was coarser than theirs (a large face's bound, a large cylinder's), only to keep every face.MITCAD_MESH_TRACE=1logs each meshing's faces, phases and slowest faces. While a handle is dragged, Extrude also shows a provisional tool at once (mitcad#636;framework/DragProxy,framework/CommandSessionProxy.cpp,CommandDef::dragProxy,commands/ExtrudeDragProxy): when an exact preview is installed, its tool's interactive-tier triangulation is copied on the UI thread into an owned, immutableProxyMesh(the job that made it is over and nothing writes into a stand-in), with the inputs it was computed from and the tool's placements in the design (the report'stool_instances, which also place the exact tool now). Each dragged value then changes a copy of that mesh on the UI thread: Extrude stretches it along the dragged arrow about its start (one side), its middle (symmetric) or the profile plane (two sides, one side only), or moves it for the start offset; only for distances without a taper, from the profile plane or an offset, not wrapped, and only while every other input is as the exact preview had it. The arrow's direction is taken into the tool's coordinates through each placement and must give the length the values say, or nothing is shown.OcctViewer::setProvisionaldraws it see-through amber with dashed edges, unpickable, hiding the exact tool meanwhile; no model query, no job and no worker-owned shape is involved, and the bounded scheduler of mitcad#634 computes the exact previews as before. An exact preview of the value dragged to replaces the proxy; a structural change, a typed value, a failed, cancelled or cleared preview, OK, Cancel and the session's end remove it. The automatic operation and the targets still follow the exact previews only.MITCAD_LOG_TIMING=1logs each update; every drag logs its inputs, proxy updates, exact previews and frames drawn (OcctViewer::framesDrawn) apart. Move/Copy's handles drive a provisional motion instead (mitcad#838;CommandDef::dragMotion,commands/MoveDragMotion): when an exact preview is asked for (the model idle), the command works out what its motion needs of the model (Free Move's pivot, the placement of the component the move works in) and keeps it with the preview as a function of the inputs. Rotate's axis and the points of Point to Point and Point to Position are taken from the exact preview itself: the model reports whatMoveSpec::resolveworked the motion out of (the preview'smotion), andDragMotion::resolvemakes the function of the inputs from it, so a drag turns about the very axis the result turns about. Rotate's ring runs about that reported axis too (previewReportedkeeps it with the Axis pick it is of;keptRotateAxis): the model takes a circle's axis in its canonical direction, which may be against the circle's own, so the ring's sense, the proxy and the result agree. Move Face shares the ring (rotateRingAxis) and keeps its preview's reported axis the same way (mitcad#854:move_faceresolves its motion throughMoveSpec::resolveand reportsmotion, also when the preview fails); it has no provisional drag motion, since its body is not moved rigidly. Each dragged value then draws the exact preview's bodies where it puts them: a body the move moved or copied at its placement times the change, a body of an occurrence it places with the change taken into the design before its placement (draggedPlacement). The view keeps a body that is only placed elsewhere and moves its drawn objects (OcctViewer::placeBody,AIS_InteractiveContext::SetLocation), so a drag costs no model query, no presentation and no meshing. While the handle is held and the bodies follow, the exact preview waits until the pointer rests for 250 ms or the button goes up; it then replaces the provisional placements and stays what OK commits. The exact result reuses the meshes too: a rigid motion of a Move or an Align places the body as a location on its own B-rep (geometry::move_shape,Kernel::move_shape) instead of a transformed copy, so its faces keep their surfaces and triangulations and both tiers find them meshed (the input is not changed; it shares its sub-shapes with the result). Mirrors, scales and mesh bodies are copied as before. - Background evaluation of the rolled-back features (mitcad#1267,
DocumentSession,core/ffi/src/background.rs,core/model/src/document/rolled_back.rs; the log lines in app/COMMANDS.md). An edit before the marker gives every rolled-back feature new inputs, so none of their cached results fits and a marker moved forward evaluates each as it passes it. At the session's idle point after a job (no timer), with the mode idle (no command panel, no sketch), the marker before the end and a state no run went through yet, the session makes a fork of the idle document on its own thread (Document::rolled_back_run:Document::forkwith the marker at the end, reporting to a monitor of its own) and runs it on a secondModelWorkeratQThread::IdlePriority(the Utility quality on macOS), never on the model worker, so the user's jobs do not queue behind it; one run at a time. The fork shares no mutable state with the document: its definition and cache are copies whose results are shared read-only, its kernel isKernel::fork's, and the shapes both hold are only read by its evaluations, as by the import's forks and the recompute's workers. What could write into them is kept apart: every job first cancels the run and waits for it to stop (stopBackgroundEvaluation: the run's monitor, the kernel's long operations stop inside an evaluation, P7e), since a job may mesh new bodies that share their faces; and no run starts after a job that was asked to stop, whose meshing may have left bodies the view meshes on its own thread. The view itself, which goes on while a run reads the bodies, never meshes a model shape (mitcad#1553): faces are drawn from the meshes the jobs made, and every line (a body's edges in every visual style, highlights, the hover, the hover chain) from detached copies of the edges (app/view/ViewEdges.hpp, mitcad#1633): new edges on the same curves, made when a body is shown and dropped with it, each with its polyline cut at 0.001 mm and at most 4° a step, whatever the body's size; a highlight of a body's edge takes the body's copy, so that it lies on the line it highlights, and the hover's owners draw their face or edge so too. Smooth seams (mitcad#1773,geometry/include/mitcad/geometry/smooth_seams.hpp: an edge with the same face on both sides, or between two pieces of one face on one surface, by OCCT's surface or the faces' names, where the normals agree within 0.01 rad) keep their copies but are left out of the drawn lines in every style and out of the edge selection (dropSmoothSeams), so no line is hovered where none is drawn;model_render's raster leaves them out by the same rule (Mesh::face_surfacesand the seam copies' normals). Plates draw bodies no job meshed through a copy, and the section clips made on the UI thread clip detached copies (prepare_clips); an edge highlight that meshed the body's own edge there damaged the heap under a run's join (tools/ui-view-mesh-writes-test.sh). What the view does mesh on its thread is its own: sketch profiles, sketch curves and datums are built there anew from the model's numbers (Document::profile_shape, the sketch and datums queries) and handed to no model thread (mitcad#1586, the test's driver checkexpect-view-own-shapes); sketch curves and projected curves get their polylines with the same parameters as the bodies' lines, so that a projected curve lies on the edge under it (tools/ui-edge-mesh-test.sh). A command or a sketch that opens cancels it at once without waiting (cancelBackgroundEvaluation). When it ends (or a job stops it), the document adopts what it evaluated on the session's thread while no job runs (Document::adopt_rolled_back): only when its definition is still the run's (the marker aside), the features nearest the marker first, and no more than the memory cache's budget leaves beside what the document's results hold; the fork goes before the cache is trimmed, since it holds every result it was made with. Versions are fingerprints, so an adopted result of another state could never be taken wrongly; the check only keeps memory from results never used. A feature that fails in the run is not reported (failures are not cached), and each run logs one line at its end (and one as it starts).MITCAD_BACKGROUND_EVALUATION=0turns it off. Not yet: the fork has no result store, so it evaluates what a marker move could have read from the store, and OCCT's own thread pool inside an operation is not lowered with the thread. - macOS computation scheduling (
app/platform/macos/MacWork.mm, throughMacChrome.hpp, mitcad#556): model and section workers setQOS_CLASS_USER_INITIATEDon entering their thread loops. Before either worker starts, the application explicitly sets that class on every thread of OCCT's default pool through a launcher job, so display meshing and parallel sections use it too. This starts the existing pool earlier, without changing its size or the calling UI thread's class; it does not depend on pthread QoS inheritance. Autosave writes, texture-folder scans and result-store garbage collection useQOS_CLASS_UTILITYfor each task, restoring the shared thread's class when the task returns or throws. Result-store writes remain synchronous model work, with the model worker's class. Each model job and section round holds anNSProcessInfoactivity; rendered-view and final-render clients hold one while their render session runs, and the windowless render worker holds its own until its renderer is destroyed. RAII and process-exit/error handlers end them on completion, cancellation and worker failure. The activity option isNSActivityUserInitiatedAllowingIdleSystemSleep: it prevents App Nap while permitting normal system idle sleep.NSActivityLatencyCriticalis deliberately omitted because it requests high-priority I/O intended for audio/video recording, without evidence rendering needs it. Native tokens and scheduling calls stay inplatform/macos/; other platforms use inline no-ops. Qt remains the default macOS UI. - Section Analysis off the UI thread (
app/framework/SectionWorker,app/MainWindowSection.cpp, mitcad#438): the clips of the bodies shown, their meshes for the view and the panel's area and length run as rounds on a thread of the section worker's own, not as model jobs: the model prepares what a round needs while the document is idle (Document::prepare_clips,prepare_query: the bodies' shapes, the planes in their coordinates) and the round works it out without the document, so the window stays responsive (no progress dialog, input taken, the view drawing what it showed) and the result is shown on the UI thread when it is ready. One round runs at a time: a newer plane stops the running round through the geometry's cancel and replaces those waiting, so no stale result is shown and nothing piles up; the measurement waits for the view's round. A round never reads a sub-shape of a body the UI thread draws: what it works on is detached when it is prepared (Kernel::detach_all: copies that share no face, edge or vertex with the bodies the plane may reach, and of the others only the box they keep), so the view's meshes, a clip the UI thread makes itself (Hide Above Sketch, a body the kept clips lack) and a model job, which write into the bodies' sub-shapes, may run beside a round. A model job still tells the rounds to stop (DocumentSession::setBeforeJob, not waiting), as their result may be stale after it, and they are done again once the window is idle. The clips of the plane last clipped are kept (by body, shape and placement), so the bodies shown again at that plane are not clipped again. The panel's measurement is an inspection'slaterQuery, answered throughCommandHost::measureLater(at once, as a query, for other hosts). - Insert an open design (
app/files/MainWindowOpenDesign.cpp, mitcad#1172):insert.open_designlists the other liveWindowManagerdocuments by stable window handle. The shared Qt combo and dialog also use the native macOS adapters. A modified or unnamed source asks to save through its own controller beforeinsertComponent(path)reads the saved file and asks Linked/Copy. The original destination is retained through source activation and save dialogs; QPointer and registry checks reject closed owners. Self references are excluded by document identity andsameFilePath, including aliases. No document model or undo history is transferred between windows. - Document windows (
app/WindowManager, mitcad#1172): one process owns severalMainWindows, each retaining its ownDocumentSession, worker, command, selection and undo history. The manager assigns stable UI window handles, tracks the active document, canonicalizes open paths to avoid duplicates, and routes New/Open either to an empty Untitled window or a new document. The optional current-window preference retains replacement. Frontends subscribe towindowAddedand provide presentation throughsetPresenter; document frames never move model state between owners. Accepted closes unregister the document before deferred widget deletion; Quit applies each document's existing save and lock guards in order, and a cancellation stops it. The last closed document ends the process. - Document owner (
app/framework/DocumentSession): owns the Rust document, model worker, active command, selection, mode and file/recovery state.MainWindowretains reference aliases for existing workflows. Queries are allowed only while idle; a cached snapshot remains available during computation. The native command presenter uses asynchronous jobs and callbacks on the UI thread. Input changes invalidate pending previews; cancel waits for the worker, restores the native command checkpoint's definition, saved state and exact undo/redo history, then releases it before the session finishes. Legacy workflows keep their existing synchronous wait presentation through an injected handler. - Assistant setup (
app/mcp/ConnectAssistantDialog): one discoverable dialog configures local clients without owning a model or changing undo. A Rust TOML planner preserves unrelated config and comments; supported CLI registration runs on a private copy before an atomic, backed-up update. MCP Bundles contain a standalone native launcher for the installed bridge. Initialized client labels are UI metadata, never authentication identities. - MCP (
core/mcp,core/ffi/src/mcp.rs,app/mcp): the live application profile exposesdocument_list,model_query,model_command,model_export,model_reference,document_save,document_open,document_newand the application's ownui_state,ui_log,ui_screenshot,ui_select,ui_commandandui_cameraagainst the target window's actualDocumentSession. One process listener routes optional document handles throughWindowManager; omitted handles use its active window, while chat markers retain their owning document (mitcad#1172; #265,app/MainWindowMcp.cpp,app/MainWindowMcpUi.cpp). Save As (document_savewith a path) and Open reach only the folders for designs (app/mcp/AgentFolders: Preferences › AI Assistants,--mcp-folder; none by default, #402), live mode's counterpart of headless mode's workspace.document_new(mitcad#1266) makes an empty design there, in the current project (itsnew_design) or untitled, in a newMainWindowbeside the caller's, never in place of one; the listener then sends the client's omitted handles to it, and a chat agent may use the designs it made beside its own. Replies that move the view (ui_camera,ui_select's reveal,view.*commands) end the view's animation and any pending fit first (OcctViewer::settleCamera, #405), so their camera and the next screenshot agree. Each connection has a RustLiveSessionfor protocol state and a pending request; it owns no detached document. The FFI prepares a validated tool and wraps its completed result. What MCP allows follows each command's and query's class in the model's API (core/model-api/src/classes.rs: model, file IO, remote, internal), with a narrow headless exception:import_print_profileandimport_slicer_presetsremain file-IO commands, but the workspace backend permits their design-only form. It snapshots every selected and inherited source through the workspace's canonical path checks before any array entry runs. A caller-supplied Rust reader then feeds the ordinary import logic from memory; installed slicer discovery and print-library reads are excluded. Preparation shares the command memory guard and one call-wide limit of 4,096 file reads, 4,096 directory entries and 64 MiB of source bytes plus expanded preset snapshots. Document-aware stored-font checks still apply. Live mode keeps the file-IO refusal. The read-onlydesign_reviewquery lives in the Rust model API and reports stable rules with guide topic/anchor links. Print checks reuse the existing analyses and the effective printer of the selected body's shown placement. Both MCP profiles collect direct command targets and reuse the same query for at most three short hints;hints: falseavoids that query. No new geometry or undo step is created. Commands follow the ordinary window workflow and run on the same model worker; in an open sketch its own commands go throughSketchOpas the user's would, and an agent's undo steps are labelled "(agent)". Queries are refused only while the model computes (a busy result with when to retry); a command panel, drags, dialogs and edit locks guard model commands, and replacing the document invalidates its handle.ui_commandruns registry commands through the panel's own actions (CommandSession::scriptInputs) and closes any modal dialog it opens (mcp::ModalGuard); a dialog already open waits for the user, and the refusals andui_state'sdialogname it (mcp::dialogRefusal, mitcad#1725);ui_logreads a ring of the application's log lines (mcp/LogRing). The agent indicator (mcp/AgentIndicator, mitcad#710), beside the project indicator, names the initialized sessions and can disconnect them. A listener binds only to IPv4 loopback on an allocated port; a private per-user discovery record supplies an instance ID, the process id and authentication token; records of processes no longer running are skipped and removed (mcp::processRunning, mitcad#437).mitcad-cli mcp --connectdiscovers and authenticates a running instance, then bridges standard MCP stdio to its JSON-lines socket without exposing the token on stdout. Bridge EOF leaves the GUI and unsaved document open.--no-mcpdisables the listener. The separate headless--workspacemode retains its own documents and confined file tools (mcp.md). In both, amodel_commandis an error only when it is refused or a feature it added or edited fails; the model'sfailed_features(each failed feature,edited,new;core/model/src/document/command_outcome.rs) go to the top of the result, andmitcad_mcp::command_outcomedecides for both profiles (#401). Amodel_commandtakes an array of commands (one undo step; a refused entry undoes the earlier ones; an entry takes what an earlier one made by name,"as"and{"ref"}, checked and replaced bycore/mcp/src/array_refs.rsfor both profiles, mitcad#1897) and answers with what it changed, compared in Rust (core/mcp/src/changes.rs: snapshots before and after, the shape versions of thebodiesquery,recompute_times); the livemodel_exportwrites into the folders for designs with the headless server's command and checks (Document::mcp_export_plan), andui_screenshotreturns an MCP image block (mitcad#689) within a caller-selectable encoded-image budget,max_bytes(app/mcp/ScreenshotBudget.cpp, mitcad#1188). - Chat panel (
app/agent,core/mcp/src/chat.rs, mitcad#947, ai-chat.md): the user's own agent through its own native interface, one class per agent behindagent::ChatAgent(Claude Code's print mode with stream-json,agent::ClaudeCodeAgent; Codex's app server with JSON-RPC,agent::CodexAgent, the bridge given as the thread's configuration overrides). The built-in agents receive the live server's instructions and the compiled guide index before the first message: Claude Code through an atomically written file in the chat data folder and--append-system-prompt-file, Codex through the thread'sdeveloper_instructionsconfiguration, and API agents in their system prompt. The guide index comes fromcore/mcp/src/guide.rs, so changes to its topics reach all three paths from one source. The agent's only tool source is the live server of its window, through the installed bridge with the chat's marker (mitcad-cli mcp --connect --chat-session); the listener asks the panel (mcp::ChatGate,agent::ChatController) before each call of that connection and holds it, and that connection's next requests, while a card waits for the user. The conversation reads the undo depth and the document's revision around the agent's calls and merges a message's steps into one (merge_undo) unless the user changed the design meanwhile. The history is a JSON Lines file per design in the user's data folder. What does not need Qt (the agents' streams as panel events, command lines, the approval policy, the undo merge, the history format, the tool calls' group rows, Codex's whole JSON-RPC exchange) is Rust, reached throughagent_chatrequests andChatStream(feed_line, andcontrolfor a protocol with state of its own: its events include the lines to write). The panel is Qt in both layouts (aFloatingLayout::Anchor::Rightcard, a dock). The AppKit frontend (mitcad#1075) shows the same panel, its Qt widget hidden, through the presenter bridge in a card of its own (platform/macos/NativeChatCard.mm, placed byNativeMacWindow): the panel says when it changed (ChatPanel::contentChanged) and is told when it is shown (setPresented); its message field's keys come from the AppKit text view (NativeTextEditorCommands). - Logging (
app/mcp/LogRing,app/framework/DebugLog, #269): one message handler for the whole run, installed bymain()after the UI test driver's and passing every message on to it: a ring of the newest 5000 lines (live MCP'sui_log, the problem reports) whose sink is the debug log. That writes the lines to a file while it is switched on (Preferences' Diagnostics page,--debug-log [FILE],MITCAD_DEBUG_LOG), with a header (version, build, system, graphics, command line, design, switches), flushed every second and at each warning, rolled over at 20 MB, the folder kept to 10 files and 200 MB. - Imports run in a separate process (
mitcad --import-worker) so a kernel crash or hang only kills that process. Nothing of an imported file is read in the application's process (mitcad#922): the listings asked before the import (the documents an.f3d/.f3zdesign refers to, a building project's linked models) run in that process too (--list-references,--list-links), behind the progress dialog, and a reader's fault there fails the import with "the import process stopped" instead of ending the session. A design file of another format imported into the open design as a component (mitcad#1894) goes the same way: the worker writes the imported design, and the application inserts that design file withinsert_component(a copy, or a linked file saved in the project), so the open design never runs a reader either. The parsing queries that do run in the application (dxf_info,svg_info, the DXF and SVG inserts, the print settings' read) run their reader throughreader_guard::catch_panic(core/model-base), which turns a panic into the query's or command's error instead of an abort at the bridge. The worker hands the import's evaluation back in a result store of the import's own (every result a store takes,hand_off_results); the window reads the imported design with it, restoring those results rather than evaluating every feature a second time (mitcad#413). Stop keeps what was imported (the worker readsstopon stdin); Cancel kills the process. The.f3dimport's one question (keep the imported bodies that match the file's on a retry on its stored bodies, or replace them; #283) goes through the job (RecomputeMonitor::ask): the worker prints it (import-ask), the window asks the user and writes the answer to its stdin. Items whose results deviate from the file's (#379) are asked about after the import, with the design in the window (so that a row can select its faces): the items the user keeps parametric make the window run the worker again with the same options andaccept_deviations, and the new document replaces the first. Inside it, the.f3dand.iptimports guard their memory themselves (#80, #60): low on memory, they give up definitions and finish with the file's bodies rather than end the process. The IFC import (#273) stops before its next element and reports the rest as not imported. - Rendering (
app/render/, in every build since #141; the configure stops without the prebuilt Cycles and Open Image Denoise): View > Rendered shows the visible bodies path traced by Cycles in the render workermitcad-render, an executable of its own next tomitcad. Only the worker links Cycles and its libraries (Embree, Open Image Denoise, OpenImageIO, OpenColorIO); the application links none of them and offers View > Rendered when the worker is installed. A worker the user built (an OptiX one, which MitCad never ships, mitcad#1332) can be picked in Preferences; the shipped one is its fallback. Commands go over its stdin and stdout as JSON lines (its first line names its protocol version, which the application checks); frames come back through anonymous shared memory (amemfdwhose file descriptor goes over a Unix socket; a namedQSharedMemoryon Windows), which cannot outlive the two processes, and become the 3D view's background, under OCCT's overlays, which the bodies' depth hides as in the shaded view (the image is a layer over the bodies, under the overlays). The worker follows the view's camera and size and gets scene updates written while the model is idle: every body by id with its mesh's content hash, placement and material, and only the meshes it does not hold (glTF), so that a change sends only what changed; and the document's render settings: the environment, the background's visibility, the ground and the user's lights as anenvironmentcommand; the exposure, the view transform and a background colour are applied by the application when it shows a frame. Frames have two planes: the bodies' light over a transparent ground, and the ground's shadow catcher factors per colour, which multiply the background behind it (shadows, coloured reflections; #54). OnlyCyclesRenderer.cppincludes Cycles (C++20); the rest is C++17 (rendering.md). The worker renders on the CPU or a GPU (#50: Cycles' CUDA device, which the Linux and Windows releases ship, #202; Metal on macOS; HIP or oneAPI in builds with their SDKs): the device is a per-machine setting (Preferences > Display, the user's settings), sent as the worker's first command; a device that is not there or fails hands over to the CPU, which renders the same scene and says why (RenderDevices.cpp). The final render (Render Image,mitcad-cli render, #48) runs the same worker in a batch mode on a job file (scene, environment, camera, output settings): it writes the image file itself (PNG and JPEG with the view's exposure and view transform, OpenEXR as linear light) and reports progress and previews on stdout; the application stays usable and can cancel it. - Sheet metal (#210,
app/commands/SheetCommands.cpp): the SHEET METAL group's commands keep no sheet model of their own. A pick on a sheet body is a face or edge named by its material domain; the model'ssheet_referenceandsheet_seamqueries turn it into the semantic panel, bend, boundary or corner the definition stores. The browser lists a sheet metal body's rules and Flat Pattern fromsheet_bodies; a Flat Pattern shown flat replaces the body's display with its developed solid (analysis_shapeflat_pattern), and its DXF is written by the model from the evaluated outline (export_flat_pattern_dxf, sheet-metal.md). - Updates (
app/update/): see updates.md. - Web pages (
app/web/, mitcad#423): a design as one self-contained HTML file, since browsers block module scripts andfetch()fromfile://.WebGlbwrites the visible bodies as a binary glTF file in the design's unit and frame (Z up, as the model; the viewer turns the data'supitself): one node per placed body (n1,n2, …; the component tree in the page's data names them), each body meshed once on a copy of its shape (io::triangulate, the export's tolerances), the appearances as metallic-roughness materials with their texture images inside and texture coordinates by the rendered view's projection (a mesh's own where its appearance lays the image by them, mitcad#1862).WebPageadds the data (units, tree, named views, Home) and inlines it, with the viewer'sviewer.jsand its modules asdata:URLs of an import map, into the viewer'stemplate.html; the viewer's files are Qt resources (:/web-viewer/<repository path>).writePagereads the open design throughCommandContext(Export › Web page, on the UI thread while the model is idle);writePageOfFileloads a design file without a window (load_design, links followed, computed with the result store) and may run on any thread. - Component from Web (
app/webbrowser/, mitcad#1579): the only part of the application on a web engine, the Chromium Embedded Framework, in the web browser component: a package of its own (the modulemitcad-webbrowser, CEF's subprocess helper and runtime) that MitCad downloads on first use, verifies against the signed update manifest (BrowserComponentInstall, the bridge'supdate_browser_checkandupdate_verify_browser_downloadincore/update), installs in the user's application data and loads at run time; never in the installers. The module links Qt and CEF only and asks the application for the rest throughComponentBrowserHost(the import, the bridge's zip reader, dialogs, menus, sizes, colors, folders), whosekComponentBrowserAbiboth sides check. CEF runs windowless, its loop pumped from Qt's, each page painted from its software buffer into a widget (CefView) that forwards input; its GPU process draws WebGL on the GPU, or in software (SwiftShader) where there is none (mitcad#1861, app/COMMANDS.md), and in software only from the next start after the GPU path failed, with the browser's WebGL, GPU and page errors in the feedback diagnostics through a property of the application object (mitcad#1906,webbrowser/BrowserDiagnostics.hpp); CEF is given the view in physical pixels at a scale of 1 and the page's zoom is the display's scale, as CEF paints windowless frames at 1 whatever it is told (mitcad#1657, app/COMMANDS.md).ComponentBrowseris a window of its own with one browsing profile for the application; its downloads go into temporary folders (WebDownloadFolders, one locked folder per run) and pass the format filter (ComponentWebFiles, plain Qt Core, by name and first bytes), and a zip's files are listed and unpacked through the host and the bridge (zip_list,zip_extract,mitcad-zip). The design side (MainWindowComponentWeb.cpp) is ordinary JSON commands:create_component,import_file,set_property(the part number) andmerge_undointo one step, then Move/Copy (app/COMMANDS.md). - Texture sources (
app/materials/, #315): where Edit Appearances finds sets of texture maps. Each source is one class behindTextureSource(asynchronous categories, search, thumbnails and fetch; answers delivered on the GUI thread, dropped when the asking object is gone) and one line intextureSourceRegistry();FolderTextureSourcescans the folders of Preferences › Textures on a worker thread. The browser (TextureBrowser, aQListViewgrid with thumbnails asked for as they come into sight) sits inAppearanceDialog; Use turns the fetched files into onecreate_appearancewith every image embedded (textureUseCommand), so the model never sees a source, the network or the cache (textures/<source>/<asset>/<resolution>/in the local data folder,MITCAD_TEXTURES_DIR), and a design never needs them to open.PolyHavenTextureSource(#313) is the online one: Poly Haven's public API, the list of textures, each texture's list of files and the thumbnails kept in the cache (so the service is not asked again and again), the chosen resolution's maps downloaded and checked. Its requests go through aTextureFetchergiven to it (TextureFetcher.hpp): Qt Network in the application (HTTPS only, User-AgentMitcad/<version>, nothing while Preferences does not allow the network), fixture files for UI tests (MITCAD_TEXTURE_FIXTURES), a fake with recorded answers in the unit tests, so no test uses the network. - Feedback and error reports (
app/report/, #61, #62): Help › Send Feedback and the reports offered after a crash or an internal error share one path: areport::Reportof sections, masked (home folder, other absolute paths, user and host names) before the preview, where the user edits, leaves out or cancels; then the issue tracker's form, filled in through its address and opened in the browser. MitCad holds no token and sends nothing itself; a relay service could take the delivery's place later. The tracker is a build setting (MITCAD_ISSUE_URL) with a user setting over it. Crash capture is plain C++ (CrashHandler.cpp) in the application, the import worker andmitcad-render: signal handlers (Linux, macOS) or an unhandled exception filter (Windows),std::terminate, and a Rust panic hook that leaves the panic's message (core/ffi/src/panic_note.rs); each writes a text report (header, stack, recent actions) into the crash folder and lets the process die as before. The stack comes frombacktrace_symbols_fdon Linux and macOS; on Windows it is walked from the exception's context (StackWalk64, on a thread of its own), so it starts at the faulting function, and dbghelp names the frames from the PDB file next to the executable where there is one (module and offset otherwise). On Linux the executables export MitCad's own symbols (app/report/crash-symbols.list) so that stacks name its functions. The application offers a worker's report at once (it watches the folder;MITCAD_CRASH_PARENTtells its workers' from others') and its own at the next start. The duplicate key is a hash of the signal and the top frames as module and function, with the handlers' own frames and addresses left out, so the same crash in another run, folder or machine gives the same key; an internal error's is a hash of its message with numbers and paths replaced. Send Feedback's Include the design (mitcad#1795) adds no delivery of its own: the model'sdesign_packagequery (core/model/src/document/design_package.rs) writes a zip of the open design and the files it refers to inside its project, with the report, the screenshot and the log, intoreports; the user attaches it to the issue or e-mails it, and the body only names it. - 3D view (
app/OcctViewer): an OCCTV3d_Viewin aQOpenGLWidget; OCCT renders into FBOs and needs a native drawable to make Qt's context current on. Linux: a GLX 4.5 compatibility context with a hidden helper window (a core profile makes OCCT read Qt's pbuffer and crash). Windows: WGL, the window of Qt's offscreen surface. macOS: a 4.1 core context, the highest Apple offers.viewportSurfaceFormat()sets the existing platform format as the default beforeQApplicationexists, so the global share context and viewports have compatible profiles.Qt::AA_ShareOpenGLContextsis also selected before the application: Qt retains each viewport's same context when a document moves between top-level frames, preserving its OCCT shaders, meshes and selection. This follows Qt's documented QOpenGLWidget context-sharing lifecycle. A native drawable change still replaces OCCT's context wrapper. DuringSetWindow, the old wrapper stays alive until the shared shader manager points at the new wrapper; otherwise releasing the old owner can clear that pointer even though Qt's native context remains valid. Each paint binds the manager to the view's current OCCT wrapper after Qt activates the native context.MITCAD_LOG_GL_BINDINGS=1logs the Qt/current/OCCT wrapper and shader-manager identities and the explicit ownership check. The macOS drawable is the top-level window'sNSView. The GL assumptions stay in the surface format andocctDrawable(), so that another backend stays local (OCCT has no Metal one). The orientation cube and pick widths scale with the device pixel ratio. The view meshes each body at an absolute deviation by its size (mitcad#1275): a thousandth of its bounding box's diagonal, at least 0.01 mm (parts under 10 mm across) and at most 0.5 mm, in steps of the square root of 2 (io::shape_deviation); its edges with 12° (cut in steps of 6°), its faces' insides with 15°. Those are the faces' meshes; the lines drawn over them are cut apart, finely and the same for every shape (mitcad#1633,app/view/ViewEdges.hpp). Small circles and arcs (Preferences › Display › Small circles, Adaptive by default, mitcad#879) are cut by that deviation alone where it allows fewer pieces than the angle, in at least 12 a turn: their edges' angular deflection widened and the edges discretized again, cones, tori and spheres of such a radius with their angles widened as far (MeshOptions::small_circle_segments); Full Detail keeps the angle for every circle. The choice keys the stored display meshes, and a change re-meshes the shown bodies on copies and gives them the new triangulations once the job ends (remeshForDisplay,giveRemeshed). The exports' presets do not take it. A machine of 257 bodies took 5.3 million triangles at 0.01 mm everywhere. Every face that is not a plane is held within 20 000 triangles, a small face within a quarter of a triangle per square of its deviation in its area: one that comes out with more is triangulated again with a larger deviation (MeshOptions::hold_face_triangles; a small part's B-spline faces took 56 000 each). The faces whose deviation only the size raised record 0.01 mm, the drawers' deviation, so the drawers keep them; their edges' polygons keep the deviation they were cut at. And each doubly curved face is meshed within about 20 000 triangles beforehand (app/view/ViewTessellation.hpp, #398): a face that would take more (a sphere of metres took millions) meshes with a deviation that grows with its size (geometry/iomesh.hpp,face_deviation_floor). Cylinders and cones mesh at most as finely as a turn in 500 straight pieces (mitcad#438): their triangles are mostly their edges' points (a circle of 6.8 m radius took 2 600 at 0.01 mm), so those of radii over about half a metre, and the edges that bound them (at the smallest floor of their faces, planes having no say, and no more than their own curve's), mesh with a deviation of 2e-5 of the radius (about 700 points a turn, as BRepMesh cuts edges at half their deviation); smaller ones, and edges shared with small faces, at the body's deviation. OCCT's presentations mesh through that algorithm (use_bounded_presentation_meshes, BRepMesh's default for the process); the model's worker makes the same meshes beforehand (mesh_in_place, for all the bodies of a job at oncemesh_all_in_place, one meshing per deviation), and the exports' presets bound their faces the same way (commands.md, Mesh refinement), at their own deviations (not by size, not held). A pattern of bodies moves its copies as locations on the body's shape (Kernel::move_shape, as a Move's copy, mitcad#838), so their faces are the body's and the view draws every copy from the body's meshes. A window selection of whole bodies decides by the bodies' boxes first (OcctViewer:: decideWindowByBounds): a body whose box the window holds is taken, one it misses is not, both without OCCT's pick, which tests their triangles; only the bodies it crosses are left to OCCT. - Theme and icons (
app/framework/Theme,Icons): dark mode is read from the application palette (isDarkPalette), and the error, warning and accent colours and theset*StyleSheethelpers follow palette changes. The palette is the platform's, except on Windows 10, whose default style keeps a light palette in the dark app mode: there, while the app mode is dark, Qt's own style (QFusionStyle) with a dark palette of the neutral roles (app/platform/WindowsTheme, mitcad#1282). Preferences › Display › Theme (app/framework/AppTheme, mitcad#1330) asks the platform for a light or a dark scheme whatever the desktop's (QStyleHints::setColorScheme; System: the platform's own), and where the platform keeps its palette, sets the same palette of the neutral roles itself (themePalette), light or dark. The SVG icons are rendered on demand at the asked size and device pixel ratio. Their colours are roles (IconRole): each source#rrggbbstands for one role (outline, lit top, side and far faces, pale surface, hollow, construction, action, sketch, pencil, muted, status), and each role has one colour and opacity per theme, written asfill-opacity/stroke-opacity/stop-opacity; the same on every platform. Amber is for construction and inspection only. A disabled icon draws every role in the outline colour and the whole icon at 34 %. - Interface languages (mitcad#1460, translations.md):
English is the source language of every
tr()text. Each other language is a Qt Linguist fileapp/translations/mitcad_<code>.tsand a line oflanguages.txt; the build compiles it (cmake/Translations.cmake, the tooltools/translations) and the packages carry the.qmfiles with Qt's ownqtbase_<code>.qm.framework/Languageinstalls them inmain()before any window or command definition takes its texts (--language,MITCAD_LANGUAGE, Preferences › General › Language, else the system's first language when MitCad has it), with a context-free part of the catalogue for texts whose context at run time differs from the source's, and keeps the English source of every translated text (the command search matches English names). A language is data: no code lists languages. The model's messages (mitcad#1284) stay English in the model, the JSON API, MCP and the command line; the application translates what it shows (framework/ModelMessages): a message is matched to its template, the English text of its Rust source with the values as%1,%2, ... (its id), and the template's translation (contextModelMessage,app/translations/model_<code>.ts) gets the values back, a value that is a message translated in turn. The templates are generated fromcore/(tools/translations,messages;app/framework/ModelMessageTemplates.cpp, checked by the ctestrepo.model-messages), so the model needs no change to make a message translatable: a new message is a new template.
The Qt idle selection card uses the model's single-item measure query for
up to eight selected faces, edges or bodies. Results are cached until the
selection changes or the scene refreshes, so edits and undo invalidate them.
Full topological references remain in the tooltip. Floating cards size their
active page independently of the hidden sketch palette. The palette sits in
a scroll area in both layouts: in the floating command card it keeps its
rows at their size hint and scrolls when the card (limited by the view's
height) is shorter, instead of being squeezed below its hint (mitcad#470).
The idle page (the selection's card, the Autoselect rows) scrolls the same
way in both layouts: in the Docked layout a dock's minimum height is its
content's, so content that grows with the selection or with rows would make
the main window taller, up to past the screen (#412, mitcad#560). No
dock's content may raise its minimum height with what it shows; the window
logs its layout again whenever its size changes after it shows.
The AppKit frontend is paused (owner 6.11.2026): it is not built and macOS uses the shared Qt UI (macos-shared-qt.md). What follows describes it as it was, for when native UI work resumes.
With MITCAD_MACOS_NATIVE_UI=ON (the macOS presets and releases until
6.11.2026), macOS builds carried both frontends and started Qt by default (mitcad#1056). The
preference appearance/nativeMacInterface (Settings › General) starts the
AppKit frontend; main() reads it before the application object exists.
--ui=native|qt overrides it for one run; --chrome without --ui also
selects Qt. --ui=native requires the native build option. The start-up's
Frontend: line names the frontend and what chose it. The native frontend keeps
the single-document workflow and the macOS 14.4 deployment target.
NativeMacWindow owns an NSWindow, configurable NSToolbar, model
NSOutlineView, inspector, and collapsible horizontal feature history with
coloured icons and an in-row marker. Timeline filtering uses the shared
component filter while preserving model indices; playback skips boundaries
inside hidden feature runs. The native toolbar presents the shared project,
live-update and edit-lock status and opens the shared project menu.
Saved toolbars receive the Project item once when upgrading an older layout;
later status changes and application restarts preserve its explicit removal.
The menu bar, application delegate, Finder open requests, document edited
indicator, Services, text editing and window actions are AppKit's. The
application delegate forwards methods it does not override to Qt's previous
delegate, preserving application-state signals, activation hover updates and
secure state restoration. Startup disables Qt's native menu bar rather than
using plugin mode, so the Cocoa integration still installs Qt's delegate.
Dock reopen runs Qt's handler before presenting the
native document; termination and file-open requests keep the shell's policy.
The saved document frame restores both its origin and size; only a window
without a saved frame starts centred with the default content size. System
controls, semantic colours, fonts and sidebar material follow the running
macOS version and accessibility settings. The toolbar changes in sketch
mode; command definitions and saved shortcuts remain shared.
The shared command registry validates shortcut proposals against commands
which can be available together, fixed application/menu keys and effective
alternate bindings. Profile-accepting model features also run in sketch
mode; other Model/Sketch pairs can share keys. A command of several
contexts can have its own key in each (mitcad#720; shortcuts.<context>/<id>
beside the all-context shortcuts/<id>); the window sets the current
context from its mode, and the actions carry that context's keys. Alternates apply only while
the proposed primary remains its default. Conflicting legacy custom
bindings remain saved for repair in Keyboard Shortcuts, but are disabled
at runtime with a diagnostic; their menu actions remain available. The
registry exposes the same effective keys for Qt actions, native dispatch,
NativeText hints and the shortcut overview.
CommandPresenter separates command-session actions and displayed state
from controls. NativeForms builds real AppKit inputs from InputDef;
CommandPanel remains the Qt presenter. Only one presenter is attached to
a command. A preview being computed goes to setBusy (the Qt panel's busy
mark beside OK and Cancel, which changes no size, mitcad#1907), not to the
message. The AppKit form lays its captions and controls out as the
shared form does and hands its OK and Cancel to the window as a footer
under the scrolling inputs; its value fields run the shared
ParameterField expression tools on hidden Qt proxies
(NativeControls, mitcad#815). Secondary dialogs and Settings use NativeDialogs, which binds
the existing hidden Qt presenter models and signals to AppKit controls.
Those widgets initialize their existing workflows but are never drawn.
Presenter-tree events and control/model/selection signals coalesce into one
queued native refresh; unchanged AppKit properties are left alone. A 500 ms
safety net covers Qt properties without notify signals, including model
replacement, row hiding and index-widget changes. Its model check hashes
visibility and widget identities without reading model data or allocating
description strings; nodes and selection are rebuilt only when dirty.
Sketch inline editors follow presenter/ancestor geometry events and their
host's move, resize, screen and backing-property notifications.
File and colour panels use explicit AppKit sheet hosts. File presenters
select widget-backed storage before setting their initial file and filter,
so AppKit can read them without showing a Qt chooser. Native alerts and
secondary modal sheets preserve existing synchronous result semantics;
native command previews, inspections and commits use the asynchronous model API.
Physical Properties carries ordered section and label/value rows through
Inspection::report into a shared QFormLayout. Each value is a plain,
selectable label and only body/Total section headings are emphasized. This
keeps both frontends' two-column report semantics without flattening an
HTML table or drawing interactive widgets as images.
The Comments window uses the same bridge for its six-column native outline, reply hierarchy, status filters and actions. Its shared presenter retains selection and scroll state while model commands refresh the rows; selecting a comment selects and frames its target. Model accessibility roles carry the full comment and reply content into AppKit rows. Comment pins remain shared viewport overlays, and the native navigation bar and chat panel use the shared Comment Pins action and Comments attachment toggle.
Child windows of a presenter (context menus, message boxes) are not part of
its native structure, so they never rebuild its controls or move their
keyboard focus. A presenter can opt its outline into row drags
(setNativeRowMoves): it keeps the rules, the outline carries the drag. The
Projects panel uses that and gives the native window its tree keys
(ProjectsPanel::treeKey) and a visible row name editor
(ProjectsPanel::setNativeEditor, platform/macos/NativeProjects.mm), so
the native outline drives the same project actions (mitcad#816).
The viewport alone remains Qt/OCCT content. A standalone viewport host is
embedded as a native sibling of the AppKit panes through the public
QWindow::fromWinId(NSView*) and QWindow::setParent APIs. No private Qt
platform API or replacement geometry/rendering kernel is used. AppKit owns
the outer window and resizes the embedded drawable; general Qt overlay
buttons are suppressed. A failed native attachment is reported at startup
instead of leaving an unusable canvas. OpenGL focus, frame pacing, fullscreen,
display changes and hardware rendering require the manual checks in
native-macos-ui.md.
The following layouts describe the retained Qt frontend.
chromeStyle() (app/framework/ChromeStyle) picks the layout at start-up:
Docked (the ribbon in a toolbar, the panels in docks) or Floating
(the default everywhere since mitcad#429; the Browser's Rows background by
default on Windows and Linux). Preferences › Display › Layout chooses
one for the next starts (appearance/layout, layoutPreference(); a change
offers to restart, framework/Restart), and --chrome=docked|floating
overrides both for a run (mitcad#419). MainWindow builds either from the
same panels, so object names and the positions the UI tests click are
the same in both. The ribbon's workspace tabs are Solid and Build
(#375: slot-profile assemblies, whose commands call only the
model's BUILD commands and queries; app/COMMANDS.md, BUILD), with Sketch
after them while a sketch is edited; while a drawing is open the Drawing
tab alone (Cut Sheet for a cut sheet) holds the drawing's tools and the
drawing covers the whole 3D view (mitcad#1008; app/COMMANDS.md,
Drawings); the AppKit frontend lists BUILD's commands in a menu and
shows the Drawing and Cut Sheet tabs the same way (mitcad#1073). Before
them all is the Start tab (mitcad#1258; app/COMMANDS.md, The Start
tab): a page without groups, for which the window shows the Start page,
a child of the 3D view covering it as a drawing does, the cards and docks
hidden meanwhile; the AppKit frontend shows the same page over its
embedded view and hides its cards (NativeMacWindow::setStartPageShown).
Its designs' browser (mitcad#1301, app/files/StartBrowser) lists the
recent designs and the projects as File › Open from Project's data does
(app/projects/ProjectBrowserData, readProjects on a thread), with one
search over every project and the recent list.
Docked has a look of its own, WindowStyle (app/framework/WindowStyle,
#251), the same on every platform and in both themes: the docks and
the ribbon's toolbar are raised surfaces (slightly lighter than the window,
rounded, 6 px apart: the main window's separators are the gap and paint
nothing); each dock's title bar is a PanelTitleBar with its title in
small grey text, preserving its spelling, and float and close buttons that
show while the mouse is over it (the timeline's is a strip at its left); one accent colour, the
icons' action blue (actionColor), is the palette's Highlight and Accent,
the selected rows' rounded bands (28 px rows, stylePanelTree), the
timeline's selection and its marker's handle, and the ribbon's selected
tab's pill; the Command panel's Autoselect has a section title instead of a
group box. The colours (windowColors) follow the platform palette's theme
and are set again when it changes. On Windows 11 the title bar takes the
menu bar's colour, with Mica and rounded corners, and the font is Segoe UI
Variable (app/platform/WindowsFrame.hpp).
Floating is a full-window 3D view with the panels over it:
TitleBar: one toolbar-high row under the native title bar (the content extends under it; empty parts move the window): Undo and Redo, the ribbon's tabs as a segmented control, the document name with the project indicator beside it and the command search. Finish Sketch stays in the ribbon's Finish Sketch group and the Sketch Palette. Under it the ribbon inPresentation::Mac(capsule groups whose name opens a menu of all their commands), and the update and remote notices. That is macOS's header above the view; on Windows and Linux (floatingTopCards(), mitcad#425) only the menu bar is above the view, and the title bar row (aGlassCard,titleCard), the ribbon's groups (Ribbon::setGroupCards: each group a card, the ribbon masked to them) and the notices (noticeCard) are rows of cards over the view's top (FloatingLayout::addTopRow).GlassCard: the rounded Browser, Command and Timeline cards and the message band's card. The Command card shows only while it has something to say. There is no status bar; messages go to the message band right above the timeline (mitcad#1042:MessageCenterkeeps the session's messages and what the band shows, byMessageLog's rules;MessageBandis the band's content,MessageHistorythe history over the window;FloatingLayout::setMessageBandkeeps the band's row below the other cards). Docked keeps its status bar, with a button for the same history.FloatingLayout, the central widget, owns all card geometry: cards are anchored to the view's corners (Browser upper left, Command upper right under the orientation cube, Timeline along the bottom), sized by their content up to a share of the view, laid out in one queued pass. A Command card taller than the room under the cube grows up to the top first, the cube moving to its left (the right inset), before it scrolls (mitcad#655). The upper left cards (Projects, Configuration, Browser) are one column (mitcad#1020): they share its height, each at most its content's, the rest evenly or by the user's split, which a drag of the gap between two of them sets (shareColumn,floating/leftSplit). It gives the view the free margins (OcctViewer::setOverlayInsets) and covered rectangles (setCoveredRects): the cube and its buttons stay clear of cards, picks and logged click positions avoid them, and Fit, Home and the named views fit the model into the free area (fitToFreeArea). Cards take the mouse only inside their rounded rectangle. No card starts above the bottom of the header (the title bar row, the ribbon, the notices), whose size and place the layout follows too (mitcad#419), or above the last row of top cards (mitcad#425), whose cards the view gets as well (OcctViewer::setTopCards: the free area starts below them, picks are refused inside them only, so that the view picks between them). The Browser's card is as high as its rows down to the card below it, then scrolls (maximumContentHeight).
Why the cards are windows. With glassActive() (macOS 26+, Floating,
no --no-glass) a card's material is the system's Liquid Glass
(NSGlassEffectView). Qt's OpenGL content covers any native view inside the
main window, so each card is then a frameless top-level window of its own
(GlassCard::setWindowed), attached as a child window of the main window
(mac::attachGlassWindow), and the window server composes the glass over the
real 3D view. Without glass the cards are child widgets that paint their own
material. GlassCard and FloatingLayout hide the difference: card places
are slots in parent coordinates mapped to the screen and kept there when the
main window moves, resizes, minimizes or goes full screen; card windows stay
out of the Window menu, the window cycle and other Spaces; a card window
without a focused widget forwards keys to the main window's focus widget
(GlassCard::forwardKey); a command panel that focuses a value field
activates its card window first when another window of the same main window
has the keys (focusField in CommandPanel.cpp); logged positions are in
host window coordinates (GlassCard::mapToHost). Their visibility follows the
owning FloatingLayout page as well as the physical window: switching document
tabs hides every native card, and background message updates only change its
requested state. Returning to the page restores that state. Moving the document
to another frame also replaces the layout's physical-window event filter.
Dialogs modal to the main window are sheets on macOS (app/framework/Dialogs:
prepareModal, sheetWarning, sheetInformation, sheetQuestion). On
macOS Preferences is SettingsWindow, a pane per Preferences page whose
changes apply as they are made, and About is the standard About panel.
The default Qt frontend also uses macOS presentation for Command Search and Edit Parameters. Their platform helpers use the system font, SF Symbols, native search fields and buttons, and palette-derived table and selection colours. Layout dimensions are logical pixels, so the controls and their icons follow the display's backing scale. Parameter editing and command dispatch stay in the shared widgets; the appearance does not change which frontend is selected.
The shared MacDialogs.hpp extends those conventions to library/part,
browser/project/settings and render/build dialogs (mitcad#645): native search
fields and SF Symbols, source lists, unframed sections and readable tables.
Unchecked table cells have an explicit palette-derived checkbox outline;
checked/mixed cells retain native painting, and the model/delegate keeps
mouse and Space editing. Library tiles use rounded image selection and a
separate caption highlight. Role-based QDialogButtonBox layouts follow the
platform's button order; explicit primary defaults prevent auxiliary actions
from taking Return. Escape follows each dialog's close/cancel path, including
stopping an active or queued final render. Icon-only controls retain their
accessible names and tooltips. Shared UI labels use the single ellipsis
character; menu/log-name normalization accepts both forms.
The AppKit print managers use the shared MaterialsPanel and
ProfilesPanel controllers, including own-place library editing and
no-design operation. The platform bridge preserves their outlines,
swatches, settings and destination menus. Explicit field-focus requests
carry F2 and newly created items' focus/selection to AppKit; opted-in
appearance-list keys call the shared removal handler. Native divider
sizes survive presenter rebuilds through the retained splitter.
The platform layer. app/platform/MacChrome.hpp declares the
AppKit-only functions in mitcad::mac: SF Symbols as icons in the palette's
colours (symbolIcon), menu images hidden in the menu bar and shown in the
ribbon's menus, the hidden native title, the glass child windows, the About
panel and captureOwnWindows (the application's own windows as the window
server shows them, for tests). app/platform/macos/MacChrome.mm implements
them (Objective-C++, ARC); elsewhere they are inline stubs in the header, so
portable code calls them without #ifdef. app/platform/WindowsFrame.hpp
does the same for Windows (mitcad::win): the Docked window's Windows 11
frame through DwmSetWindowAttribute (skipped before build 22000, decided
at run time) and the Segoe UI Variable font, implemented in
app/platform/windows/WindowsFrame.cpp. Q_OS_MACOS branches in portable
files are for Qt-level behaviour only (the GL format, shortcuts).
A design is one .mitcad file. Single-file design (format 2):
{"format": "mitcad", "version": 2, "units", "parameters", "features": [{"uid": "F3", "type": "extrude", ...}], "bodies", "marker"}, plus
components, occurrences, active_component, root_component, a
feature's component when present, named views and analyses. Version 1 files
are converted on open. Parametric geometry is not stored; a feature that
split bodies keeps the volume and centre of each piece (split_pieces,
#408) so the pieces keep their ids. Imported bodies
live in base features as OCCT binary BRep, zlib + base64
({"format": "occt", "compression": "zlib", "size": n, "data": "…"},
core/model/src/features/base.rs); their faces are named
<feature>:import(<j>). A base feature added from shapes (an import, the
.f3d import's fallbacks) is evaluated from those shapes the first time
(Kernel::adopt_shape, #244): the body its data reads as, without
reading the data back, sharing the shape's B-rep and keeping what was
measured of it that does not depend on face names. Later evaluations read
the data. A body whose bodies before it were taken out of its base
feature (Find Repeated Parts, mitcad#1277: copies made occurrences of one
component) keeps its id and face names by its entry's number and
first_face.
Design in a project (format 3): a project is a folder with the
marker .mitcad/project.json. Designs inside keep base-feature B-rep
data in a content-addressed store, .mitcad/brep/<aa>/<sha256>.brep.zlib,
referenced as
{"format": "occt", "compression": "zlib", "size": n, "sha256": "…"}.
Store files are written once, before the design file, so the JSON stays
small and diffable. A file is version 3 only when it has such references.
Opening resolves them from the nearest enclosing project and checks size
and hash; missing data fails its base feature with a message. The
per-user display state (Origin folder, Isolate, View › Show's hidden
kinds) is kept out of versioned
files in .mitcad/local/display/<path>.json. Autosave and the import
process always write single-file designs (format 2).
Size limits on reading (mitcad#928): a design file and its project's
store come from other people too (git, cloud sync, zip), so sizes are
checked before anything is inflated (features/base.rs,
build/sources.rs). A B-rep's size is at most 512 MiB (MAX_SIZE)
and at most 64 times its zlib data plus 1 MiB (max_inflated); all the
B-rep data one file decodes, inside it or from the store, is at most
2 GiB (MAX_FILE_SIZE, a per-thread FileBudget while load_state
reads). A library source's design text in the store is inflated to at
most 512 MiB and max_inflated of its store file, and the sources'
texts together to at most 2 GiB; a store file that decodes to more is
"damaged" and leaves the source a reference with a warning.
Id numbers on reading (mitcad#929, mitcad#944): a session hands out
new ids by counting on from the largest its design holds: components
(C<n>), occurrences (O<n>) and their numbers, features (F<n>),
sketch points, curves and texts (p<n>, c<n>, t<n>) and constraints
(k<n>), library sources (S<n>), drawings (D<n>), their views,
annotations, cut-sheet parts and export counts. A file chooses those
numbers, so reading refuses any of them in the top ID_RESERVE = 2^20
numbers of its type (core/model-base/src/ids.rs: at most
LARGEST_U32_ID = 4293918719, a feature at most LARGEST_U64_ID =
18446744073708503039; file/id_reserve.rs), in the words of a malformed
id: components[0]: invalid component id C4293918720 (at most C4293918719: …). The id text forms themselves still refuse only the
type's largest number, so commands name the ids a session handed out.
This reserve was chosen over allocation that can fail at every counting
site: one rule on reading covers them all, and every session keeps about
a million ids of each kind, far more than it makes, so counting on never
overflows (a panic in Debug, a wrap to duplicate ids in release before).
A design that came in just below the bound and was saved with ids in the
reserve is refused on reading like any other such file.
Autosave publishes immutable snapshots named
<session UUID>.<generation UUID>.mitcad in the user's recovery folder.
An atomic replacement of <session UUID>.json (autosave metadata version
2) points to the completed snapshot. The prior snapshot remains until that
replacement succeeds, so failed or interrupted updates preserve the last
completed generation. Recovery still accepts metadata version 1 with its
fixed <session UUID>.mitcad snapshot. Snapshot names are validated before
recovery reads them; obsolete generations are removed after publication or
when the session is discarded. Every document window owns its own UUID,
manager, write pool and lock, so a normal close removes only that
window's records. Recovery selects all healthy records and restores each
into a separate document owner, reusing an initial empty window once.
Live/lock/remote controllers remain document-owned; their session comes
from that document's autosave UUID. Library updates, favourites, broker
credentials/notices and the debug log remain process services. The debug
log's design fact lists all open document paths.
DocumentSession divides the configured process model-cache budget among
live document owners, returning shares when an owner closes. A busy model
receives the current share through whenIdle, after its worker releases
it. Loading a replacement uses that owner's share, rather than the full
process budget. The on-disk result store remains shared.
Code: Document::save_file (atomic: temp file renamed over),
load_design, from_json_at, from_json_in with a BlobStore
(core/model/src/file/project.rs: FsStore, MemoryStore; core/vcs
adds GitTreeStore). mitcad-cli project init and
convert --format v2|v3. project init writes:
# .gitattributes
*.mitcad text eol=lf merge=binary
.mitcad/brep/** binary
# .gitignore
.mitcad/cache/
.mitcad/local/
.*.tmp
eol=lf protects files from core.autocrlf; merge=binary makes git's
own merge treat a design file changed on both sides as a whole-file
conflict instead of producing valid JSON of a broken design. Temp files
of an interrupted save are .<name>.<process>.<n>.tmp. On Windows the
rename is retried for up to 2 s while another program holds the file
(file::rename_retrying).
core/vcs, gitoxide (gix =0.88.0, default features off: only sha1,
index and blocking-http-transport-reqwest for libraries over HTTPS,
mitcad#1224; a default feature pulls in an MPL-2.0 crate). No gix types
in the crate's API. JSON commands: commands.md
("Version history").
- MitCad commits only when the project folder is the root of a git repository, so a user's enclosing repository is never touched.
- A version is a commit built from HEAD's tree plus the saved paths (like
git commit --only), adding the B-rep files they reference and removing unreferenced ones.index.lockis held for the round and only committed entries change, so the user's staged changes survive andgit statusstays clean. No commit when nothing changed, HEAD is detached, or a merge/rebase is in progress. - Store reads and version recording refuse symbolic links in the metadata
directory, store, shard directories and files. Before adding a store file,
recording checks its complete zlib stream and SHA-256 of the uncompressed
data with bounded streaming memory. Project clones persist
core.symlinks=falsebefore checkout, so remote links become plain text. - Author: the repository's own
user.nameanduser.email(New Project and Project Settings write them), else git's configured user, else Preferences' default author. Messages end with trailersMitcad-VersionandMitcad-Format: 3. - A file's history is HEAD's first-parent chain, following content-
preserving renames. Open, Restore and Compare follow that lineage even
when another design previously used the current filename. Explicit
versions outside the first-parent chain use the requested path. Older
versions are read from the commit tree with
GitTreeStore, no checkout. Restore writes the old content back as a new version; history is never rewritten. - Comparison (the crate
core/model-diff/): two document snapshots are compared in model terms without computing them (parameters by name, features by uid with moves, definition fields, sketch elements, components, bodies, views; optionally computed volumes and areas). The model has no git: the vcsdiffcommand reads texts from trees, the bridge'sdiff_documentscompares open documents.
In the app (app/files/MainWindowVersions.cpp): Save in a project with
history writes the file, then commits on the UI thread (it reads saved
files, not the document); a failed commit leaves the file saved. The
message is the undo labels since the saved state
(changes_since_saved), excluding display-only changes. Before
overwriting, Save compares the file's blob ids in the folder and HEAD
(status) with those at open/save and asks on a mismatch. A file renamed
outside MitCad (status's renamed_from) takes its display state along
(follow_rename), and the next save records the rename first. Projects
are made by the core's create_project (below); an older project without
history gets it from init_project_history. Autosave never records a
version.
The Version History window (app/files/VersionHistory.cpp) reads history
on its own thread with its own Project (a project is single-threaded):
the list first, then per-version summaries. Geometry comparison runs as a
job on the model worker. Open loads a version as a new untitled design;
Restore saves or drops unsaved changes first. Each Save keeps a 256 px
preview in the user's local app data, thumbnails/<blob id>.png.
gix has no push or checkout, so the network operations of projects run
the system's git (component libraries over https:// excepted, below)
(core/vcs/src/remote/cli.rs; MITCAD_GIT, else PATH, on Windows also
Git for Windows' usual folders; 2.34+): ls-remote, fetch, push,
clone, merge --ff-only. TLS, SSH and credentials are git's (SSH
agent, credential helpers). git runs non-interactively (no stdin,
GIT_TERMINAL_PROMPT=0, setsid outside Windows), with LC_ALL=C so
failures can be classified (errors.rs), GIT_ALLOW_PROTOCOL limited to
ssh/https/http/file, and -c core.autocrlf=false -c core.eol=lf. Runs
are cancellable and time out after 5 minutes without output. MitCad never
handles passwords: URLs with credentials and ext:: helpers are refused,
and credentials are hidden in output.
A repository's own git configuration is untrusted input (mitcad#920,
core/vcs/src/remote/trust.rs): a project folder may arrive from
anywhere with its .git, and git runs on open without a question (the
edit lock, the quiet fetch). Before every run, GitCli::run reads the
configuration of the repository git would use there (config of the
common git folder, config.worktree; no includes followed) and refuses
(class untrusted_config, git not started) when it sets a key that starts
a program, sends the sign-in or traffic elsewhere or moves the work tree:
core.sshCommand, core.gitProxy, core.askPass, core.worktree,
remote.*.uploadpack/receivepack/vcs/proxy, credential.*helper,
url.*.insteadOf/pushInsteadOf, http.* (but transfer sizes),
protocol.*, filter.*, diff and merge drivers, gpg.*,
push.gpgSign, include/includeIf, init.templateDir, git-lfs's
transfer agents. These are refused rather than overridden because their
safe value is the user's own configuration (an SSH command or credential
helper that signing in needs). What has one safe value is overridden on
every run instead: core.hooksPath=/dev/null (no hooks, also none from
.git/hooks), core.fsmonitor off, no submodule recursion; so a team's
core.hooksPath does not refuse a project. A fetch, push or
ls-remote addressed to a configured remote checks its url and
pushurl with check_url first. Projects MitCad created or cloned set
none of the refused keys. remote_info names the refusal
(untrusted_config), which the project indicator shows.
A remote in a folder (a path or file://) is untrusted too (mitcad#940):
git runs that repository's own git on this computer for a push
(receive-pack, with its pre-receive, update, post-receive and
reference-transaction hooks) and a fetch or listing (upload-pack),
and the -c overrides above do not reach it (git clears them for a local
remote). So check_run finds the address a network command reaches (the
named remote's pushurls for a push, else its urls, also from the
legacy remotes/ and branches/ files; else the operand itself) and, for
a folder, puts --receive-pack='git -c core.hooksPath=/dev/null -c core.fsmonitor= receive-pack' (--upload-pack=… for fetch,
ls-remote, pull, clone) right after the command, and refuses
(untrusted_config) when the configuration of that folder's repository
sets a refused key (core.alternateRefsCommand, filters or
core.worktree for a push that updates its work tree). Remotes on a
server get no such option: their hooks are the server's. Tests that need
a remote that refuses lock refs hide them by its configuration
(receive.hideRefs=refs/mitcad) instead of a hook.
- Ahead/behind counts come from local refs (
HEADvs.refs/remotes/origin/<branch>), so status needs no network. - Connecting refuses an unrelated history, sets
originand upstream, commits.gitattributes, then pushes or fetches. Pushes are never forced; files over 100 MiB are held back. Clone refuses a repository without a project at its root. - Sync (
core/vcs/src/remote/sync.rs) fetches, then replays the project's unpublished versions on top of the remote's with gix, keeping history linear. Whole files are the unit: a path changed on both sides is a conflict resolved as keep mine, take theirs or save mine as a copy; file contents are never merged. Nothing changes until every conflict has a choice; the old history is kept inrefs/mitcad/sync-backup/<time>(pruned after 30 days, newest 5 kept), thengit reset --keepmoves the branch and folder.git gc --autoruns afterwards since gix writes loose objects. - Per-user remote state:
.mitcad/local/remote.json.
In the app (app/files/RemoteController.cpp) remote work runs one task
at a time on its own thread (RemoteTask with its own Project and a
cancellable SyncControl), never on the UI thread or the model worker;
remote_info and incoming (no network) run on the UI thread. Saves push
immediately, retrying with exponential backoff from one minute; the remote
is fetched on open, every 10 minutes and at the first change (both per
project in Project Settings, Preferences' Cloud page giving the defaults).
Save and Restore wait for a running sync.
Every RemoteTask of a project (the remote controller's, the lock
controller's, the Projects panel's pushes, Project Settings' Share) waits
in that project's queue (app/files/VersionQueue, mitcad#1895), so two
never run on one repository at once while other projects' run beside
them. Commands that need no network but write the repository (Save's
commit, create_folder, new_design, move, delete) run aside on a
thread of their own while the UI thread keeps painting without taking
input, and never wait for the queue. A design leaving the window has its
versions synced and its edit lock released as one task in its project's
queue instead of a modal progress; only closing the window waits, at most
10 s.
Local and Cloud projects (#89, core/vcs/src/projects/). A project
is Local when its folder is the root of a git repository without a
remote and Cloud when the repository has one. The kind is never stored:
inspect_folder reads it (and what else a folder is: missing, empty, a
repository, designs, inside a project, inside another repository) without
the network or writes, so a project cloned with any git tool is Cloud.
JSON commands without a project go through the bridge's
projects_command with a SyncControl; a project's own are Project
commands (commands.md, "Projects").
- Made in one step (
create_project): the folder, the repository, the marker,.gitattributes,.gitignore, the author in the repository's own configuration and the first version; for Cloud the remote is checked first (nothing changes on a failure), an empty one gets the versions, one with files but no project is cloned and the project made beside its files, then a push. A failure before the first version puts the folder back as it was; a failed push leaves the versions waiting.clone_projectwithadoptmakes a repository with files a project;init_baremakes a shared folder a remote. The repository's own configuration says who made it (mitcad.repository:createdorexisting). - Removed in one step (
remove_project, mitcad#1562,core/vcs/src/projects/remove.rs): the folder stops being a project and keeps its designs. Everything is checked before anything changes (adry_rungives the plan the confirmation shows); designs that refer to the B-rep store are written as single files first (mitcad_model::file::single_file_text), the others stay byte for byte; then MitCad's lines of.gitattributesand.gitignore,.gitonly when MitCad made the repository (its mark, else a history whose first versions hold the marker), and.mitcad. The designs are found by a walk of its own, not the discovery scan: dot folders count, and a folder it cannot read or a link to a folder refuses the removal (mitcad#1598). A repository that was there before keeps its history and records a version without the project's files; a design of the latest version that still refers to the store and is not rewritten in the folder goes into that version as a single file made from its blob (commit_with_contents, mitcad#1607); a remote is never touched. - Onto a repository's files (
connectwithonto_files, Local → Cloud): the sync's replay (remote/sync.rs) puts all of the project's versions after the remote's, with.gitignoreand.gitattributesmerged by lines and other paths on both sides as conflicts; a replay that stops before it changed the project removes the remote again. - Settings: the shared ones (edit locks, the MQTT broker) are typed
fields of the marker (
core/model/src/file/settings.rs, read defensively), and a change is recorded as a version; this computer's are in.mitcad/local/. The author of versions is the repository's ownuser.nameanduser.emailfirst. - Remotes: a branch without an upstream follows
origin, else the only remote; with several and none followed nothing syncs until one is chosen: the window's project is Local with the remotes' names (ProjectState::unfollowedRemotes; the indicator says "No remote chosen"), and Project Settings asks which,remote_followsetting the branch's upstream (no network). - Folders and designs (#144,
projects/listing.rs,projects/operations.rs):project_treelists a project's folders and designs without the network or writes, each design with its latest version (counted in one walk of HEAD's first-parent history, renames followed ashistoryfollows them), whether it changed since, and its edit lock from the local copies of the last lock poll.create_folder,new_design,moveanddeleteare each one version with Save's rules (ProjectRepo::commit: only their paths, the index locked, nothing while HEAD is detached or a merge is in progress), and a Cloud project pushes it as a Save does (the application passespush: falseand pushes itself). git records files, not folders, so a folder keeps an empty.gitkeep, never listed; a move or delete that would empty a folder's versions adds one. A move records old and new paths in one version, so the B-rep store stays consistent (the commit keeps what the new paths refer to) and the history follows the rename; the per-user display state and the design opened last follow too. Refusals (a target that is there, a path outside the project, hidden or not portable, a design locked by another person, a delete that would lose unrecorded work) change nothing and are answers'errors. The listing and the commit's walk both skip every dot-folder. - What a remote or a server sends is untrusted: a check of a remote
without a project clones it without file contents into a temporary
repository that is removed, and names shown are cleaned of control and
invisible characters. SSH host keys come from
ssh-keyscan(the git installation's or the system's, no terminal, 20 s, 64 KiB) parsed in Rust: only the asked host's lines of known key types with well-formed keys, fingerprints computed here and compared with those GitHub, GitLab and Codeberg publish (built in) and withknown_hosts(hashed names too). Trusting appends to~/.ssh/known_hostsonly a key a new scan still gives and, for those services, one they publish.
In the app (app/files/MainWindowProjects.cpp) the window keeps the
current project (ProjectState: kind, root, remote; files/Projects)
as state of its own, independent of the open design's file. New Project,
Open Project, Open from Cloud, Save to Project and opening or saving a
design set it (setCurrentProject, followFileProject); an untitled
design keeps it. RemoteController, the indicator and Project Settings
use its root, never the design's path (before #89 the remote looked
for the project through the design's file and could not find a project
just made).
- Dialogs (
files/ProjectDialogs,files/ProjectSettings): New Project, Open from Cloud, Change Address and Project Settings. Save to Project (mitcad#503, File menu after Save As) uses the project picker (projects/ProjectPicker) with its New Project... button, and saves as Save As does. Open from Project (mitcad#530, File menu after Open) is a file-dialog-like window on the same data (projects/ProjectBrowser; its listing and searchprojects/ProjectBrowserData): folders left, contents right, a path bar, a search across the projects, Read-only; only whatproject_treelists, never the raw folders. New Project and Create Project Here make an empty project (create_projectwithout a design; #145), and Open Project opens the design opened last (last_design), else the newest, none for an empty project. The first two and Change Address shareCloudSection(files/CloudSection): the service, the address composed of owner (a user or an organisation; on GitLab also a group with subgroups,group/sub), repository and HTTPS or SSH (files/CloudAddress, plain Qt Core, unit-tested; the address field comes first and a typed or pasted address of any common form (https,git@host:owner/repo.git,ssh://, a browser page's address,git clone …) fills the fields back, an unknown host asowner/repositoryon a generic server; an address that is none is refused before the check,repositoryAddressProblem), and the check of the address while typing (after a pause), again when the dialog gets the focus back, on a thread of its own; its failures get their fixes (Copy Public Key and the SSH keys page, a credential helper's hint, Trust This Server's host key dialog). Folders are inspected on a thread too; a project is made (create_project) with its progress and Cancel in the dialog, and a cancel or a failure leaves the folder as it was. - The project indicator (
files/ProjectIndicator) replaces the status bar's version and remote labels: in the docked layout's status bar, in the floating layout's title bar row beside the document's name. It shows the project, its kind, the open design's version and the remote's state (RemoteController::indicatorState), and has the project's menu. - The AppKit frontend observes the same indicator state and opens its menu through the native menu presenter. Native asynchronous model commands enforce the shared edit-lock policy; checkpoint bookkeeping remains available to finish inspections and cancel an in-flight edit after a lock is lost.
- Hooks for the edit locks and live updates (the lock controller, below):
ProjectIndicator::setLockText,setLiveText,setLockActions;ProjectSettingsHost::stoppingSync,settingsChanged,probeLocks,testBroker;MainWindow::m_openingReadOnlywhile Open Read-Only opens a design. - The Projects panel (#145,
app/projects/) shows the projects, their folders and designs: project → folders → designs (#173: a project row is its repository's root, nothing groups the projects), with the sync state, versions, edit locks and changesproject_treegives (no network).ProjectsTree::readProjectsreads the known projects (ProjectsSettingsin the application settings, remembered bysetCurrentProject) and the projects folder's on aRemoteTaskthread, each with aProjectof the thread's own; the panel reads again after Save (updateVersionStatus), a sync or a push, a change of its own and when the application gets the focus back, and only while it is shown. The panel only shows and asks; the window (projects/MainWindowProjectsPanel.cpp) runsnew_design,create_folder,moveanddeleteon the UI thread as Save records a version (afterRemoteController::waitForBranch, with the project's author andpush: false), then sends the current project's versions throughRemoteController::versionRecordedand another Cloud project's with apushtask. A move of the open design takes the window's file, version base and edit lock along (openDesignMoved, the lock throughLockController::designSaved); deleting it closes it. Renames and new names are typed in place (QTreeWidgeteditors), drags are the tree's own mouse handling (no system drag and drop: nothing leaves the panel). In the Docked layout it is a dock split above the Configuration dock and the browser's (the view keeps its width); in the Floating one a card, whichFloatingLayoutstacks above the Configuration and browser cards (upper left cards stack in the order added; mitcad#1020). It starts hidden until the user shows it. The rows give the names the width (mitcad#529): the state as compact marks (projects/ProjectRowText), a name that does not fit elided in the middle by the rows' delegate, and the width dragged by the panel's edge and remembered (the card's grip,GlassCard::setWidthAdjustablewithFloatingLayout::setCardWidth; the dock's edge). The AppKit frontend presents the shared Projects panel throughNativeDialogs, in a bounded native outline above Browser. Its header disclosure collapses the content; View > Projects controls whole-panel visibility. The native bridge must preserve the panel's workflow capabilities; generic model binding alone does not establish keyboard/editing/move parity. Shown or hidden at the start (#151): the user's last choice (ProjectsSettings::panelShown, written only by a show or hide), else shown whenanyProjectConfiguredfinds a project (folder entries only, nothing opened). A project row shows a display name (#152; the project'slocal.name,.mitcad/local/name.json, per computer and never versioned), else a Cloud project's repository address without the scheme (repositoryAddressOf:github.com/owner/repository), else the folder's name; sorted by it, Local and Cloud told apart by the icon and the tooltip; row keys keep the folder's name. Project Settings from the panel (the settings button for the selected row's project, #153; a double-click on a Cloud project) is the current project'sfile.project_settings, or the same dialog for another project without opening it (panelProjectSettings: its host refreshes the panel, pushes a recorded version in the background, and has no lock probe or remote work to settle, as the window runs none for it).
In a Cloud project a design has one editor at a time (#89,
core/vcs/src/remote/locks.rs). The lock is a git ref on the remote
outside the branches, so it works with any git host that accepts such
refs; it is advisory (MitCad honours it, other git tools do not see it).
refs/mitcad/locks/<sha256 of the path>points to a parentless commit whose tree holdslock.json(holder, session, times, idle time and poll interval, state, receipts and answers); requests are refs of their own,refs/mitcad/lock-requests/<id>/<session>, so a requester never races the holder.- Every write is a compare-and-swap push (
--force-with-leasewith the expected commit, empty for "must not exist"): of two takers one wins, a takeover fails when the holder refreshed meanwhile, and a hand-over writes the requester as the owner in one step. A rejected push is told apart from a remote that refuses such refs by listing the ref again;lock_probechecks a remote once (create, list, delete). - One
ls-remoteper poll lists the lock refs, the requests and the branch head; changed refs are fetched intorefs/mitcad/remote-locks/and read with gix under size limits, every field checked, texts cleaned and numbers clamped (locks/format.rs; fuzz targets incore/vcs/fuzz). Branch fetches, pushes and Sync never carry lock refs. - Staleness never compares two computers' clocks: a ref seen unchanged
for the idle time and two polls, a request without a receipt within two
of the holder's polls, or a receipt without an answer, all on this
process's monotonic clock. The observations are kept per project folder
in the process, shared by every
Projectof it, since the application opens one per task. - Requests go stale the same way, so that a requester whose MitCad was killed is not asked about for ever: the requester's polls write a waiting request again every half idle time as a refresh of itself (its id, the commit it was first written as, stays, and with it the receipt, the answer and its place in the order); another session's request seen unchanged for the idle time and two of the requester's polls gets no receipt, is passed by in a hand-over and is removed by the next poll of whoever sees it, with a compare-and-swap deletion that a refresh in between defeats.
In the app (app/files/LockController, files/MainWindowLocks.cpp) one
lock controller per window keeps the open design's lock:
- Its lock commands run as
RemoteTasks one at a time, each with aProjectof its own; taking the lock when a design opens, polls, the refresh, requests and answers do not wait, while releasing, handing over and the sync before them run with a progress dialog (closing, quitting, the idle time). Polls come everypoll_seconds(2 minutes while live updates are connected), the refresh every half idle time, and an idle timer restarts on activity: commands, model commands that ran, selections and the camera that came to rest (not frames drawn for a highlight under the mouse).MITCAD_LOCK_TIME_SCALEdivides the timers as it speeds up the core's clock, for the UI tests. A request the window waits on is kept alive by its polls (they pass the poll interval); the holder is asked only about requests that are not stale and not declined, in the order served. - The window is editable while its first take runs, and while the remote
cannot be reached ("Edit lock not confirmed"); the lock is then taken
when the remote answers, or the window turns read-only as for a lost
lock. Saving, the designs' versions and Sync stay
RemoteController's: it asks the lock controller before Sync sends files someone else holds (sync_plan'slockedfrom the last listing, no network), leaves the newer-version notice of a design with a lock to it (a read-only window shows the editor's version, read withload_versionfrom the fetched commit without touching the file; a design whose lock was just taken is brought up to date with a sync when the remote has a newer version of it, not when only other files are newer), and runs the sync before a release (syncNow). - Read-only windows refuse edits where they pass rather than in each
widget: the commands' availability (
MainWindow::isAvailable: only the view's, inspections, exports, files, projects and versions), every model command (MainWindow::command, which the browser, the timeline, the parameters, sketches and drags all go through, throwsReadOnlyErrorfor all but the display state, section analyses and exports), the design's file (writeFile; Save as New Version of a lost lock's changes is the one exception) and sketch mode and command panels. Unsaved changes from before the window turned read-only are kept for Save as Copy or Save as New Version; other changes in a read-only window (isolation, analyses) are never saved over the file. - What others should learn at once goes to the live controller through
LiveLink(files/LiveLink.hpp: locks, requests, receipts, answers; the open design of a Cloud project, editing or read-only, also with edit locks off; the versions sent are the live controller's own, fromRemoteController::versionsSent); its events come back throughLockEvents(files/MainWindowLive.cppjoins the two): a lock, request or version event polls at once, open events say who else has the design open, and a holder's offline will offers to take the lock after a question.
An optional MQTT broker tells the open projects at once about edit locks, requests for them, pushed versions and who has a design open (#89; commands and events: commands.md). It only speeds things up: a message makes the application poll git at once, and only the lock refs on the remote grant a lock.
- All in Rust (
core/vcs/src/remote/mqtt.rs,mqtt/), so that nothing a broker or another user sends is parsed by C or C++: the socket (std::net, blocking with timeouts, one thread per connection, no async runtime), TLS (rustls with ring as its crypto; the broker's certificate checked by rustls-webpki against the system's root certificates from rustls-native-certs, and a certificate authority file the user names), MQTT 3.1.1 (packet.rs: CONNECT with a will, user name and password, SUBSCRIBE, UNSUBSCRIBE, PUBLISH QoS 0 and 1 with PUBACK and resending, retained messages, keep-alive 30 s), reconnecting with an exponential back-off. Qt MQTT (GPL-3.0 or commercial) is not used. - One connection per broker, user and prefix (
hub.rs), shared by the open projects on it; each subscribes to<prefix>/<project id>/#(the project id is the repository's first commit) and unsubscribes when it closes. The connection's will marks the sessionofflineat<prefix>/sessions/<session>: one will per connection is why presence is not under a project and why the prefix is part of the key. - Credentials: the application passes the user name and password of
the keychain for the broker it connects to; a password goes only over
TLS (
mqtt://with a password is refused before anything is sent; without one it works, with a warning). - Untrusted input (
check.rs,messages.rs): the decoder refuses a remaining length over 64 KiB before reading the packet; more than 200 messages a second end the connection; topics only of the known forms under the prefix, of subscribed projects; payloads read with serde into typed structures of a known format and version, fields checked (ids, UUIDs, RFC 3339 times, paths, branch names, numbers clamped to the settings' bounds), text for people cleaned of control, bidirectional and invisible characters; at most 64 retained messages per file. A bad message is dropped and counted, never an error. The application shows names and messages as plain text only. - State over reconnects: the session's own retained state (its lock summaries and open entries) is published again after each reconnect; QoS 1 messages are sent again until acknowledged; a session that goes offline has its open entries cleared by the sessions that follow it (reported once the broker acknowledged the clearing). Another session's open entry is given only once its presence says it is online, so that a newcomer never shows the entry of a session whose will is already on the broker; it clears such an entry instead.
In the app the LiveHub of the bridge (core/ffi/src/live.rs) takes JSON
commands on the UI thread and gives checked events through a blocking
events(timeout_ms) on a worker thread, as remote tasks run; it never
sees MQTT's bytes. mitcad-cli live test is Project Settings' Test
button.
The application's side is the live controller (app/files/LiveController,
wired in files/MainWindowLive.cpp):
- One hub for the application; its events are read on a thread of the
controller's own and handled on the UI thread. The window's current
Cloud project subscribes with what
project_settings'live_updatessays this computer uses, under its id (project_id: the first commit of HEAD's first-parent chain), and unsubscribes when another project opens, its live settings change, it stops syncing or Preferences turns live updates off. Quitting closes the hub withwait_ms, so that the others see a clean leave rather than the will. - Trust (
files/LiveBrokers): the trust question's answer per broker address in the application settings (live/brokers), Connect or Not Now; nothing connects before it, and another address asks again. - Credentials (
files/Keychain): QtKeychain (BSD-3-Clause, built from its pinned source as a static library,cmake/Keychain.cmake) keeps a broker's user name and password in the system's keychain, one entry per host and port; on Linux it loads libsecret at run time (not linked) or talks to KWallet over D-Bus, and without either the credentials are kept for the session. A broker that refuses shows a notice under the toolbar with Sign In, never blocking an open; a password goes only over TLS. - The rest of the window: the indicator's
Live/Live offline (polling);RemoteController::setLivestops the remote's check timer while live, aversionevent of another session (or a connection back after a loss) checks the remote at once, andversionsSent(a push, a sync that pushed) publishes aversion. The lock controller meets it throughfiles/LiveLink.hpp: it publishes locks, requests and windows throughLiveLink, and gets every event and the connection's state throughLockEvents; while there is none, the controller publishes the open design (open) itself. Tests run against a broker in the test process and against mosquitto (a test tool from the dev-env setup scripts, not shipped) when it is installed; fuzz targets for the decoder and the readers are incore/vcs/fuzz(nightly, by hand), those of the file readers incore/fuzz(development.md).
Libraries of parts (#64) and the community library (#63) are
git repositories with a manifest (mitcad-library.json) whose components
are ordinary designs, usually with a configuration table
(core/model-base/src/configurations.rs: named rows of parameter expressions
with selectors such as Size and Length; applying a row only changes
expressions). Formats: libraries.md.
- The model knows no git. A
LinkResolver(core/model/src/library.rs) gives a library component's text and B-rep data at a version;mitcad-vcs'sLibraryResolverreads them from the cache, the bridge installs it for the process (configure_libraries), tests give a document one in memory. A library component is a component with aLibraryRef(library, URL, commit, tag, component, path, row, licence, authors, designation); linked, its bodies are a base feature as for a linked file (document/library_parts.rs), copied, it is the design's history in the row. The table is a top-level field of the file and of the definition state (undoable, compared row by row); both are optional, so files without them are as before. - Linked files stay in the project (mitcad#929,
document/components.rsfollowed_link):update_linksreads a linked file only when its path, taken lexically against the design's folder, stays in the design's project (its folder without one); anything else is reported and not read, so a design file does not choose files outside its project for the model to open. A new link records a file in the project relative to the design's folder. Before linking, the application askslink_check, and a file outside can be copied into the project'sparts/folder with the designs it links outside too, the copies relinked and made single files (insert_component'scopy_into_project,document/link_copies.rs, mitcad#1719). - Versions per part. A part records the commit the user chose when
inserting it;
update_linksreads that commit, never a newer one, and onlyupdate_library_parts(an undo step) moves a part to another version or row. Nothing checks for newer versions on its own. Revision names follow Git's tag/branch naming rules, including Unicode; invalid names are reported as errors. Only full hexadecimal commit ids are shortened in missing-version messages. - Cache (
core/vcs/src/library/): bare clones in the user's data folder, one per URL (<name>-<8 hex of the URL's SHA-256>.git), made and updated only on request:https://andhttp://by gix's own client without the git program (core/vcs/src/remote/https.rs, mitcad#1224: reqwest with rustls, ring installed as the process's crypto provider, the system's roots through rustls-platform-verifier; no credentials, no helpers; the fetch on a thread of its own, its progress and Cancel throughControl), folders,file://and, with the setting Use the installed git program (use_git), every address by the system's git (clone --bare,fetchof branches and tags;transfer.fsckObjects,gc.auto=0so versions designs use stay); SSH addresses need that setting; read with gix's isolated options (no user or system git configuration). A part is read from the clone of its URL, else from any clone that has its commit with the library's id. Library content is data: no hooks or filters run, manifests and files have size limits, paths stay inside the repository, symbolic links are refused. The application and CLI shareLibraryCache::default_root()through the bridge:Mitcad/Mitcad/librariesin the platform's data folder. Defaults also read the older CLImitcad/librariescache as an extra source; explicit root overrides do not. Existing caches are never moved or deleted during configuration. - Community index: a repository with
mitcad-index.jsonand an entry per library (URL, licence, components, reviewed versions); search runs over the fetched indexes and libraries locally, with a licence filter; items without a licence are hidden unless asked for. - Publishing: a library of one's own is a MitCad project folder with version history; the library commands write its manifest and items, and the version history and remote commands record and push it.
- BUILD parts (#375,
core/vcs/src/library/build.rs): a component'sbuildblock (role, slot systems, length, mount frames, connector, panel and linear data) and its supplier fields are kept in the manifest as written;library checkholds them and the design against the rules of libraries.md, andlibrary_build_candidatesfits connectors to a junction the model found (build_junctions) and parts to a picker's role and system. The model never reads a library for this: the app asks the library side for candidates and passes the chosen part to the BUILD commands. - Suppliers' shops (mitcad#950,
core/model/src/supplier_shops.rs): libraries store their suppliers' part numbers only; MitCad's own list of the suppliers' shops by region (each supplier's part number form and product address patterns) makes the product links when articles are shown (supplier_links), for the region the user chose in Preferences. The list is MitCad's data and not a library's, since a design keeps its library version and the links must follow the shops. Nothing about shops is stored in a design. - Mount frames (mitcad#525,
core/model/src/document/mounts.rs,core/vcs/src/library/mounts.rs): any part's joint origins with amount(face, shaft, hole, grid, foot; the joint a placement makes). The design is what counts: an insert keeps them as joint origins of the new component (a linked part's on fixed planes, read again with its bodies), andinsert_component'smountplaces the part by one with its joint, grids by their cells; the manifest'smounts, whichlibrary_addwrites from the design andlibrary checkholds against it, tells the app which parts have frames before it reads a design.
In the app (app/files/MainWindowLibraries.cpp, LibraryDialogs.cpp)
fetches run as RemoteTasks on their own thread with Cancel; the other
library commands are local and run on the UI thread; inserts and updates
are model commands (jobs on the model worker). The component picker
(app/library/, mitcad#418) shows the library's parts as pictures for
Insert from Library and the part-choosing commands: previews are read a
few at a time while the UI is idle, only for tiles in sight; the user's
favourites are app settings, not design data; the design's library components
come from the model's library_usage query. Its groups are a tree
(mitcad#527): the libraries' answers give each component its groups'
names from the top (groups, from the categories' parent and path
names), and the app merges groups of the same names across libraries
(PartGroupTree). A part with mount frames is placed by Place Component
(app/commands/MountCommands.cpp), a panel of the framework whose
preview is the model's mount_preview; the selection made before Insert
from Library is its preselection, so a hole's rim selected first is its
Place On (mitcad#1197).
Each document window's live MCP listener publishes its authenticated
endpoint and a separate token-free, owner-only window state beside it
(app/mcp/LocalEndpoint.*). The state contains the latest UTC activation
time, the design title (TitleBar::documentTitleOf: without Qt's [*]
placeholder and the application's name, mitcad#1149) and initialized
client names. The CLI authenticates the live endpoints before choosing the one active last; an explicit --instance
chooses that instance only. The bridge holds that socket for the entire
session. Connect AI Assistant reads the window states to name local and
other-window connections; the assistant indicator retains only local
clients. Stale endpoint cleanup and ordinary shutdown remove both files.
Autosave writes unsaved work as a single-file design (format 2) with a
metadata file and a session lock to a recovery folder in the user's local
app data, never into the project (format: app/COMMANDS.md,
Files). It writes only when the revision changed. On start the app offers
sessions whose lock is stale; a recovered document keeps its file path
but is modified and has no undo history. With the design, each autosave
writes the results computed since the last save to the result store
(mitcad#1796): taken on the UI thread with the snapshot (their shapes'
bytes, Document::take_results_to_write), compressed and written on the
autosave's thread, so that a recovered design opens from the store.
.f3d designs and FreeCAD documents are replayed as MitCad features,
each step checked against what the file stores (the .f3d ASM history;
FreeCAD's per-feature shapes). What cannot be translated or does not match
falls back to a base feature of the stored bodies, and the replay
continues on it. What the report says stays on the timeline as import
notes in the definition state (#170, core/model/src/document/import_notes.rs):
the fallbacks' base features and partial items show as warnings, and an
item the file had suppressed or failed becomes a suppressed placeholder
feature at its place. An .f3d item suppressed in the file comes in as
its own feature, suppressed, where its definition translates
(#180, core/import-replay/src/suppressed.rs). The .f3d history is matched by its solids; its surface
bodies come in with the fallbacks as stored bodies, which joins and cuts
without participants then leave alone. Both run over the Kernel trait,
so they are testable on the mock kernel; the app runs them in the import
process.
The replay's geometry differs from the file's by the kernels' noise (an
earlier feature built a micrometre otherwise). The .f3d import's
geometric tolerance (import_f3d's geometric_tolerance, 0.01 mm by
default; Preferences, General) is the distance within which the replay's
geometry is taken as the file's where no exact match is: the lookups of
decoded edges, faces and vertices look within 1e-3 mm first and then
within it, and an item's new faces must lie on the file's within it
(#224, core/import/docs/f3d-fallbacks.md). Fillets and chamfers with a tangent
chain follow MitCad's own chain (edges that meet end to end in the same
direction), not only the kernel's (commands.md, fillet).
.f3d: the design streams are decoded into the dump IR (SCHEMA.md), which external dumps (route A) also use; formats in ASM_FORMAT.md and OGS_FORMAT.md. The file's single timeline is split by component: each item goes into the component whose bodies it changes, else the one that owns it (an item that changes the bodies of several components has a feature of its own in each other one, replayed there, #169), and a feature that uses another component's sketch gets a copy moved by the occurrences' placements at its point of the timeline (features work only on their component's bodies). Occurrences take the placements the file gives them at the end of its timeline (where the timeline's items put them last, which the decoder reads per item, #81; else the last captured positions, else the stored transforms), and the file's captured positions come in ascapture_positionfeatures at their points of the timeline; occurrences of components of other documents (inserted parts, fasteners) are occurrences of empty components during the replay, which the import then fills (#196,core/ffi/src/f3d_references.rs,core/import-replay/src/references.rs): each document the design refers to is imported from its own file (the reference folder next to the design, folders and files given, the GUID the file's manifest lists; the application asks for each one not found, the command line never) with its history and its own references, and copied into its component (Document::fill_component_copy), the captured positions inside it coming in ascapture_positionfeatures of it; one undo step with the import. A document not found leaves its components empty, the report naming it. The file's joints come in as joint features only where they hold where the file places the occurrences (nothing the import adds moves an occurrence elsewhere), else as as-built joints of the placements; whether a joint holds is computed from its frames before it is added, so a joint item costs one recompute (#87). Rigid groups come in as rigid groups. Mesh bodies (mitcad#1366) are no part of the ASM history: their containers (mitcad_f3d_file::paramesh, raw LZMA streams of their own decoder) are placed by the design's mesh body records (mitcad_f3d_decode::mesh), the import's geometry gives them to the replay (StoredGeometry::take_meshes), and the item that made them (MeshFeature) comes in as a base feature of mesh bodies (Kernel::triangle_body) in its component (core/import-replay/src/meshes.rs); the history's comparisons leave mesh bodies out. Their physical materials and appearances (_f3d.appearance.meshes) come in with the appearances family, joined by their mesh body records (Importer::mesh_bodies,core/import-appearances/src/meshes.rs, mitcad#1376); the import of the stored bodies alone (import_f3d,core/ffi/src/exchange.rs) brings the mesh bodies in too.- FreeCAD:
core/freecadreads the archive and XML (roxmltree, DTDs refused, nesting, expressions and B-splines bounded against hostile files, mitcad#932); enumerations are indices, mapped per FreeCAD version throughcore/freecad/data/enums.json.
How both work, their limits and corpus tests:
core/import/README.md and, for FreeCAD
documents, core/import-fcstd/docs/freecad.md.
Real files are kept
outside the repository (MITCAD_F3D_CORPUS, MITCAD_F3D_MODELS,
MITCAD_FCSTD_CORPUS, MITCAD_IPT_CORPUS;
development.md).
.ipt parts (#60) come in with their history: core/ipt decodes
the part's parameters, sketches, work planes and features from the
definitions segment into the .f3d import's dump IR, and mitcad-import
replays it against the ASM history of the B-rep record
(core/ffi/src/ipt_history.rs), with the same checks and fallbacks as an
.f3d design (core/ffi/src/ipt_import.rs; the import_ipt command), in
the import process like the others; or only the bodies stored in the file
as base features (bodies_only). The triangles of mesh features (kept in
the graphics segment, not the B-rep record) come in as mesh bodies, base
features after the replay; a part without bodies opens empty, with a
warning.
.iam assemblies (core/ffi/src/iam_import.rs; the import_iam
command, also import_ipt with an assembly) import each distinct part
file once into a document of its own with the .ipt import, and place it
as a component: its stored bodies shared as one base feature, or with
history its replayed design copied in (Document::add_component_copy).
With history, a part whose replay fails comes in as its stored bodies,
and the report gives each part's outcome; the referenced files are
resolved before the first part is imported, so that the worker's trace
counts the parts (part <n> of <m>) for the application's progress
(mitcad#507). File › Open and Import ask for the history (Parts with
their design history, remembered; app/files/IamImport.*).
IFC building models (#273) come in through core/ifc (the reader:
no geometry) and core/import-ifc (mitcad-import-ifc) on the Kernel trait
(core/ffi/src/ifc_import.rs; the import_ifc command): the spatial
structure as components (storey planes, grid axes), each element's swept
solids and booleans as features and its breps and face sets as bodies
the kernel builds from their faces and triangles (Kernel::boundary_body,
Kernel::triangle_body; the OCCT side reuses the B-rep builder of the
other imports), all of one element in one command
(Document::add_features_with: a building of thousands of elements is
thousands of commands, not tens of thousands), types' shapes as
components with occurrences, openings cut from their elements. The
report accounts for every product of the file.
.dwg drawings (mitcad#453) hold no history: core/dwg reads the
drawing and plans its components (each named block with 3D content a
component, each rigid insert an occurrence; anonymous blocks and scaling
or mirroring inserts copied in place), the B-rep records of its solids
are converted by core/asm (the text form of older drawings
through asm::text) and built by the imports' B-rep builder, its 3D
faces and meshes become mesh bodies, one base feature per component and
layer (core/ffi/src/dwg_import.rs; the import_dwg command), in the
import process like the others.
.3dm models (mitcad#1715) hold no history either: core/3dm reads the
archive and converts its B-reps (their topology kept, an edge on a
polycurve split into one edge per segment, the trim curves left to OCCT),
extrusions and untrimmed surfaces to the neutral B-rep model, which the
imports' B-rep builder builds; a B-rep it cannot build comes in as its
saved render mesh. Each block is a component, each rigid instance an
occurrence, scaling or mirroring instances copied in place; one base
feature per component and layer (core/ffi/src/import_3dm.rs; the
import_3dm command), in the import process. The reader checks every
length and count of the untrusted file against its chunk, nests chunks
64 deep at most and checks the values the B-spline code relies on
(its README).
A SubD object's control net (level 0, core/3dm/src/subd.rs) becomes
the cage of a Form feature in its component (mitcad#1757): the one place
an import makes a parametric feature of a .3dm model. A control cage
kept with an .f3d Form body maps onto a Form's cage where it is uniform
(ControlCage::form_cage) and opens as a Form on request (form.create,
primitive kept_cage); the imported body stays, since the Form's
Catmull-Clark surface is not the stored faces exactly.
.rvt projects and .rfa families (#274, #275, #333): core/rvt
reads the container (the compound file module shared with core/ipt as
the mitcad-cfb crate), the paged gzip streams, the metadata and the
file's own serialisation schema, and walks the element records by that
schema; its building module reads the building elements' parameters
(location curves, joins, layers, boundary loops, sections, cut loops,
grids, links), and its brep module the geometry the file keeps of its
elements (winged-edge B-reps in their faces' parameters, types placed by
transforms) from the partitions' geometry chains. core/import-rvt (mitcad_import_rvt)
brings a project in through the model's kernel, one component per level
with its construction plane: walls, floors, roofs, ceilings, columns,
beams and stair runs rebuilt as features
(the IFC import's feature builder, one command per element), each checked
against the IFC export of the same project when one is given (by
GlobalId) or else its stored box and undone when it disagrees; every other
element a body: a mesh of the geometry the file keeps (triangulated in
mitcad_import_rvt::geometry), else the reference's body, its saved
mesh or its box (hidden unless structural); linked models (projects, IFC
files) in components of their own (core/ffi/src/rvt_import.rs; the
import_rvt command), in the import process like the others, under the
memory guard.
SolidCraft designs (.sc or .solidcraft, mitcad#450; a .sc file
only when its format key is SolidCraft's, as other programs use .sc too,
mitcad#1622) come in with their history through core/solidcraft (the reader: the JSON document or its container,
every file format upgraded to one by SolidCraft's own steps, adapted in
third_party/solidcraft; no geometry) and mitcad-import-solidcraft
module on the Kernel trait (core/ffi/src/solidcraft_import.rs; the
import_solidcraft command, also the headless MCP server's
document_open), in the import process like the others. The file keeps
definitions, not bodies, so every feature is MitCad's own evaluation:
parameters keep their names and expressions, sketches their constraints
and dimensions, and faces and edges are found by SolidCraft's persistent
names and pick points on the rebuilt bodies, then followed by MitCad's
topological names. Components, occurrences, joints, motion links, contact sets, motion studies and sheet
metal map to MitCad's; a feature without a counterpart, or one that fails, is a
suppressed placeholder with the reason, and the report lists it
(core/import-solidcraft/docs/solidcraft.md).
A Form (mitcad#1757, the feature type form) is a body whose surface is
the Catmull-Clark limit surface of a control cage, made an exact B-rep, so
that fillets, booleans, holes and exports work on it as on any body. The
cage is the feature's stored data: vertices and faces with ids of their
own (a face is the loop of its vertices, counter-clockwise from outside),
creases with a sharpness, corners and an optional symmetry plane, whose
cage stores one half and mirrors the other. Its edits are JSON commands
(form.*, commands.md, "Form"), each
one edit of the definition and one undo step
(core/model/src/document/forms.rs); the features after it recompute.
The work is split as everywhere else:
core/subdiv(mitcad-subdiv, Rust, no OCCT): the cage and its checks, the edits (a symmetric cage's topological edits are made on the whole cage with their mirror images, and the stored half is cut from the result again), the subdivision (the rules of Catmull and Clark; semi-sharp creases as DeRose, Kass and Truong give them; boundaries as sharp creases), the limit positions of vertices, the limit surface as patches and a preview mesh for editors.core/model(features/form.rs): the feature evaluates the patches and asks the kernel for the body (Kernel::patch_body), then joins, cuts or intersects it like a primitive; an open cage gives a surface body.geometry/src/form.cpp: each patch aGeom_BSplineSurfaceand a face, sewn (BRepBuilderAPI_Sewing, 1e-6 mm) and, for a closed cage, made a solid with its material inside; each face named by its patch.
The limit surface as patches. The cage is subdivided once, so that
every face is a quad (a cage face of n corners gives n); each quad is
one patch, its parameters running from its cage corner, u towards the next
corner's edge and v towards the previous one's, so that its normal points
out of the cage. Faces are named per cage face and corner,
<feature>:cage(<face id>)#<corner> (mirror(...) on a symmetric cage's
mirrored half): a reference to F7:cage(3) finds all of a cage face's
patches, and the names stay while the cage is edited.
- A regular quad (each corner inside the cage with four edges and four quads, no crease or corner there) has a limit surface that is exactly the uniform bicubic B-spline of the 4 x 4 control points around it. Its patch is that surface, converted to a bicubic Bézier patch.
- Other quads (at an extraordinary vertex, a crease, a corner or the cage's boundary) have no polynomial limit surface. The mesh is subdivided three more times and the exact limit points of the vertices on the quad (an even 9 x 9 grid of the quad's parameters) are interpolated by a clamped bicubic B-spline whose inner knots are the means of successive parameters.
Neighbouring patches meet without a gap, with no tolerance to tune: a tensor-product interpolant's boundary curve is the curve through its boundary points alone, and the patch across the boundary has the same points there. Where that neighbour is regular, its boundary is a cubic, which the interpolation gives back exactly (every cubic is in the spline space, and the interpolant is unique), so the boundaries agree to rounding, far below the sewing's 1e-6 mm. Across a smooth boundary the interpolated patches are tangent within the interpolation's error (the tests ask less than 8° and find far less); along a crease or the cage's boundary both sides follow the crease's limit curve and meet at an angle, so a creased edge stays sharp.