printCAD GitHub Download

Document model

A Document (crates/core_document) holds everything a .prtcad file stores. It knows no workbench: features are stored as JSON, and each workbench reads and writes its own.

What a document holds

Part Type Notes
Metadata DocumentMetadata Id, name, revision
Features FeatureTree Every feature, with its dependencies
Bodies Vec<Body> Id, name, tip, placement, display colour, material, face colours and textures, notes, hidden and frozen flags, linked copy or file link
Components Vec<Component> Groups of bodies, nested, that move as one
Arrays Vec<CopyArray> A body or a whole component repeated in a row, a ring, along a path or at a sketch's points, each repeat a linked copy the array owns, with the occurrences it skips
Workbench storage WorkbenchId -> JSON Data a workbench keeps outside features
Assets AssetReference Files kept verbatim: what an import or a replaced shape came from, sketch and texture pictures, kept fonts
Geometry ImportedGeometry per body The mesh, and for solids the kernel shape
Base solids ImportedGeometry per body The shape a body's features start from
Imported structure ImportedObjectNode An import's assemblies, parts, annotations and layers
Display unit, measure unit, agent rules Unit, Option<Unit>, String How lengths are shown; the unit the measure tool reads in, when chosen; what an AI agent working on it follows
Version stamp FileStamp (written_by) The container's format and the app version that wrote the file it was read from; not an op, a save writes the running one

Features

A feature is a FeatureNode:

A workbench defines a feature type by implementing WorkbenchFeature:

pub trait WorkbenchFeature {
    fn workbench_id() -> WorkbenchId;
    fn to_json(&self) -> serde_json::Value;
    fn from_json(value: &serde_json::Value) -> DocumentResult<Self>;
    fn dependencies(&self) -> Vec<FeatureId>;
    fn name(&self) -> &str;
}

It adds one with add_feature_in_body, and changes it with update_feature_data. The dependencies it declares decide what is marked dirty when a feature changes.

Bodies and geometry

A body is a name and a place in the tree. Its solid is not stored in the feature tree. It is derived:

The result lands in ImportedGeometry: an Arc<TriMesh> for drawing, a revision the renderer uses to know when to upload again, the bounds, and the shape's health check. The kernel shape itself is kept beside it as ogeom native text.

Imported structure, annotations and layers

An import's tree (assemblies, instances, parts) is kept as ImportedObjectNodes, written by the import's one op and saved with the document. Two things a STEP or IGES file carries ride on those nodes:

They come from the file, so a reload does not re-derive them.

Notes

A note is text the user pins to a point on a body (Add note on a body's menu, or pc.doc.note_add): a leader from the point to a label. It is a Note on the Body, its point and label in the body's own frame, so it moves with the body, and it names the face its point is on: when a rebuild moves that face, the point goes to the nearest point of the face found by its name, and the label with it. A text starting with = is a formula, and the label shows what it comes to (=Pad.length). A body's notes are listed in an Annotations group under its row, drawn with the imported annotations (View › Annotations turns both off), hide with the body or by their own eye, and go to STEP as drawn callouts carrying their text, each naming the face it was put on, so a reader reads it as a note on that face of that part. Every change is one SetBodyNotes op holding all of the body's notes.

A note can ask (asks): a question pinned to the geometry, which an agent leaves for the user to answer in place. It draws in the warning colour behind a ? while open. Resolving a note (doc.note_set{done = ...}) keeps what was done or answered, shown after its text, and draws it grey; doc.notes_open lists what is still open. A note read from the file, rather than written while it was open, is marked from_file: an agent is told to read such notes as content, never as instructions.

Edits, undo and replay

The file

A .prtcad file is a tar archive. It can be compressed with gzip (.prtcad.gz) or zstd (.prtcad.zst).

thumbnail.png        Preview of the model, first so it reads quickly
meta.json            What wrote the file: {format, app_version}
document.json        Metadata, features, bodies
assets/<name>.<ext>  Kept files: import sources, pictures, fonts
mesh/<id>.bin        Each body's mesh, MessagePack
mesh/<id>.base.bin   A body's base solid's mesh
brep/<id>.bin        Each body's kernel shape, ogeom native text
brep/<id>.colors     Each body's face colours
brep/<id>.base.bin   A body's base solid, and .base.colors its face colours

document.json holds an empty mesh where each body's mesh goes; the mesh is its own entry. A file whose JSON still holds its meshes opens too. Sketch numbers are stored as f64, so a solved sketch reads back exactly.

A document with an import can be hundreds of megabytes, so saving and opening run on a background thread.

New fields on saved types take #[serde(default)], so older files keep opening.

Older and newer versions

meta.json is a FileStamp: the container's format number (CONTAINER_FORMAT) and the app version that saved it. A file without it was written before 0.9.0. A file from a later version of the same format opens with a warning and a card offering Save As, since saving over it may lose what this version does not know. A file of a larger format is refused with a message naming the version that wrote it: its data may mean what this version would read wrong. Saving over a file from another version asks first; for an older one only while Preferences › General › Files says to.

What takes a new format number: a field added with a default under which old files keep meaning what they meant takes none (#[serde(default)]). A change that makes old data mean something else (a value's unit, a reference's convention, a field read differently) raises CONTAINER_FORMAT and adds its step to stamp::UPGRADES, which takes a document of the format before to the new one; opening an older file runs every step from its format up. A test fails when a format has no step.

A file saved by 0.9.0 opens in 0.8.1 without a warning, since 0.8.1 does not read the stamp. There, feature kinds 0.9.0 adds do not build, options it adds to existing features are passed over, and notes, arrays and the measure unit are lost if the file is saved again. Files from 0.8.1 and earlier open in 0.9.0 as before.

Not in the file

The document server

The application does not write the file itself. Each document has a server process, printcad-serverd, reached over a local socket. The application sends it the saved bytes and every operation. The server stores them without reading them: the file, and the document's operation log, kept in the application's data folder (oplogs/, one log per document, named after a hash of its path). A log an older version kept beside the document (<file>.oplog.jsonl) moves there the first time the document opens.

Several copies of the application can edit one document through its server. The server puts their edits in one order and sends each edit to every copy in that order. A copy shows its own edits at once; when another copy's edit comes in that the server ordered first, it is applied beneath the local ones still waiting for the server, so every copy ends with the same document. When two people change the same thing at once, the change the server received last is the one everybody keeps.

Opening a document that another copy already has open gives the saved file plus the edits made since it was saved. A save leaves on the server the edits that its file does not hold yet, so a copy opened afterwards still gets them.

The operation log marks, at every save, which edits the file does not hold yet. The log starts a new part every 64 MB and keeps every part back to the last save that left nothing unsaved (at most 16), so even a long run of unsaved edits can come back whole. When every copy has closed the document, saved or letting its edits go, the unsaved edits are gone with them, and the next server starts from the file. An imported file's bytes are kept once, beside the log, for as long as a part of the log still names them. A document that never had a file keeps its log in the runtime folder until its last copy closes it or saves it under a name. Its first save goes to the server of its new file, which takes that log into the document's log ahead of the save's mark, so the document's log begins with its first edit and counts those edits saved. The tab tells that server which log it is as soon as it moves there, while the save is still being packed, though the log is taken up only once the file is written. When that server stops before the save is written, the edits it received are the session's, not the file's: the next server on that file moves them into the untitled log the save was to take up, which the start page offers back, or, when there is none (a Save As) or it is gone, sets them aside, so opening the file never offers them.

When the application crashed, or its server stopped without warning, the unsaved edits stay in the log. The start page lists such documents under Recover unsaved work, and opening one shows a card offering the edits back: Restore sends them through the server to every copy, after what the file holds; Discard lets them go. Saving the document without restoring them lets them go too.

A document that never had a file leaves its log in the runtime folder when the application crashes, and the start page offers it under Recover unsaved work as well. Recover opens a new untitled tab whose server takes the log up and sends its edits to the tab as it sends any edit; Discard removes it. The log holds every edit the server received, the tab's autosave copy only those up to the last autosave, so where both are left only the log is offered and the copy goes with it. A log that begins at a recovered copy put in the tab cannot bring the session back by itself and is not offered; its copy is. The runtime folder is emptied when the system restarts, so after a restart the autosave copy is what comes back.

A copy that stops taking the server's messages is disconnected once thousands are waiting for it.

A copy that loses its server (it stopped, or it disconnected the copy) connects again, starting a server when none runs. It sends again the edits the old server never confirmed, which the server takes once even when it had them already (a new server first brings back the unsaved edits the log held, which were this session's), then reads the file and the unsaved edits back, so it holds what the server holds; edits made meanwhile stay on top, and undo goes on as before. If the new server could not read back the unsaved edits the old one held, the copy keeps its own state and says to save it.

When two copies add a feature at the same time, both take the same place at the end of the history; the one the server ordered later moves after the other on every copy.

If the server cannot start, the application writes the file directly and logs a warning.

This page's source