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:
id,name, and thebodyit belongs toworkbench_id: the kind, which says which workbench owns itvisible,suppressed,dirty, and the last rebuilderrorseq: its place in the build history. Always order history byseq, never bycreated_at.data: the feature itself, as JSONformulas: formulas setting its numbers, by parameter keymade_byandpackage_source: the workbench package that last wrote it, and where that package came from
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:
- A Design body is rebuilt from its features by the kernel.
- An imported body keeps the kernel shape it was read with. Given
features, that shape becomes the body's base solid (op
SetBodyBase), kept apart from what the features build and saved asbrep/<body>.base.bin; its history starts with a Base feature built from it. - A mesh body (from STL, OBJ, 3MF, PLY, glTF or VRML) has triangles
only, until it is converted to a solid (op
RequestMeshSolid). The conversion keeps curved stretches as facets; a refine (opRequestBodyRefine, offered while the body has no features) rebuilds them on the surfaces they approximate.
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:
- Annotations. The file's dimensions, geometric
tolerances, datums and notes sit in an
Annotationsgroup under the imported model, oneAnnotationnode each: its kind, the text a label shows (Ø 35 ±0.2,Position 0.75 | A), the polylines the file draws it with and where its label goes, in the frame of the body it describes. They are drawn over the scene where that body is placed and hide with it; View › Annotations turns them all off, and each row's eye hides one. - Layers. A part node lists the layers the file puts
its body on, by name (an IGES level reads as
level 7). The property panel shows them.
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
- Every edit records exactly one operation. Each
method that changes the document builds a
DocumentOp, applies it and records it. Replaying the operations rebuilds the same document. - Derived state records nothing. Dirty flags, rebuild errors, meshes and the preview image are consequences of the operations, not history.
- Undo applies inverse operations. Each edit computes its inverse before it applies. One gesture, such as a drag or one task in the task panel, is one undo step.
- Some operations cannot be undone. An import, a new asset (such as a picture or a kept font), a shape repair, a mesh conversion or refine, a replaced shape and deleting a body that holds anything clear the undo history. Deleting a body as it was made, with nothing on it, undoes.
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
- Each file's view, the open tabs and the window and panel sizes are
kept in the application's own folder (
views.json,session.json), never in the document: a view change is not an edit. - A linked copy's shape and mesh are its source's, and a part linked from another file is read from that file; both are derived again on load.
- Cosmetic threads are worked out from the features that declare them on every evaluation.
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.