166 lines
7.6 KiB
Markdown
166 lines
7.6 KiB
Markdown
# Authoring CDSL Modeling Guide
|
|
|
|
Write one complete `cad.author.v1` document. It is declarative source for a
|
|
server compiler, not the runtime CDSL and not an execution log. Return only
|
|
the schema-valid object requested by the tool.
|
|
|
|
## Contract Boundary
|
|
|
|
Use lower-case local `name` values for bodies and features. They are symbols
|
|
within this document only. Never emit an `id`, `feature_id`, `sketch_id`,
|
|
`body_id`, `task_id`, revision, candidate, stable topology identifier,
|
|
snapshot, owner identifier, selector token, or `host_face`/`mirror_plane`
|
|
inside `params`. The server allocates identities and injects selector values
|
|
into the destination stated by the operation contract.
|
|
|
|
Use millimetres and a right-handed coordinate system unless the request says
|
|
otherwise. Put every reasonable but unstated design choice in `assumptions`.
|
|
Do not turn an assumed dimension into a deterministic acceptance target.
|
|
|
|
## Modeling Brief
|
|
|
|
Before authoring, derive this internal brief from the requirements:
|
|
|
|
- part or multi-body intent; explicit dimensions and units;
|
|
- functional datums, origin, base plane, and positive directions;
|
|
- primary volumes, holes, pockets, bosses, ribs, patterns, and finishing;
|
|
- explicitly verifiable targets versus manual targets;
|
|
- assumptions that do not affect fit, safety, or compliance.
|
|
|
|
Dimensioned request facts take precedence over proportions inferred from an
|
|
image. Ask for clarification only when a missing interface, scale, safety, or
|
|
compliance value makes construction impossible. Otherwise choose a practical
|
|
engineering default and record it as an assumption.
|
|
|
|
## Construction Order
|
|
|
|
Choose the simplest supported construction whose parameters directly express
|
|
the requested dimensions. Use a stable order:
|
|
|
|
1. establish the body and functional coordinate frame;
|
|
2. create primary additive volume(s);
|
|
3. create any selector-hosted feature before its named source output is
|
|
changed by a fuse, cut, shell, pattern, or finishing operation;
|
|
4. add remaining bosses, ribs, and other major additive geometry;
|
|
5. make remaining pockets, bores, and through features;
|
|
6. apply patterns, then fillets and chamfers last.
|
|
|
|
Every feature must list each feature it actually uses in `depends_on`.
|
|
Prefer one complete profile-driven feature for a planar silhouette. Use
|
|
primitives when their axis, radius, and height directly express the part.
|
|
For through cuts, choose the operation's through extent and make the tool
|
|
cross the material; never rely on coincident faces or a guessed nearby face.
|
|
Delay dress-up operations because they can alter downstream topology.
|
|
|
|
The selector-source rule is an intentional exception to a generic “all adds,
|
|
then all cuts” sequence. For example, a bolt circle hosted on an original
|
|
flange cap must be placed immediately after the base when later additive
|
|
fusions replace that exact cap. A required final through-cut can still follow
|
|
all additive features and the earlier bolt operation.
|
|
|
|
Use only the supplied operation list. Follow each operation's parameter schema
|
|
exactly, including required sketch state. Do not invent unsupported operation
|
|
parameters, implicit booleans, or a substitute operation after a capability
|
|
error.
|
|
|
|
## Sketches And Coordinates
|
|
|
|
Keep a sketch to exactly `workplane` and `profile`. The workplane declares its
|
|
origin, `x_dir`, and normal. Profile coordinates are local to that workplane.
|
|
For primitive axes, `origin_mm` is the start-cap center and `direction` is the
|
|
positive build direction. For a selector-hosted hole, position coordinates are
|
|
world coordinates unless the operation contract explicitly says otherwise.
|
|
|
|
The Authoring sketch syntax is deliberately smaller than Runtime CDSL. For
|
|
every sketch operation, emit exactly this shape. `profile` is singular,
|
|
circles use the requested `diameter_mm`, and the local center is `center_mm`:
|
|
|
|
```json
|
|
{
|
|
"workplane": {
|
|
"origin_mm": [0, 0, 12],
|
|
"x_dir": [1, 0, 0],
|
|
"normal": [0, 0, 1]
|
|
},
|
|
"profile": {
|
|
"type": "circle",
|
|
"diameter_mm": 56,
|
|
"center_mm": [0, 0]
|
|
}
|
|
}
|
|
```
|
|
|
|
Do not write `profiles`, `plane`, `support`, `radius_mm`, `center`, or any
|
|
other key inside an Authoring sketch. The compiler derives Runtime radius and
|
|
sketch identity. Use a primitive such as `cylinder_add` when its axis, radius,
|
|
and height directly express the requested geometry and no sketch is needed.
|
|
|
|
Name features for their manufacturing role, for example `base_plate`,
|
|
`front_hub_boss`, `center_bore`, and `bolt_holes`. Names make dependencies and
|
|
repair diagnostics readable; they are not server identities.
|
|
|
|
## Selectors
|
|
|
|
The operation metadata states whether `selectors` are required, their kind,
|
|
cardinality, and server-side destination. Put only declarative selectors in a
|
|
feature's `selectors` array. Never write the destination field itself inside
|
|
`params`.
|
|
|
|
For an output face, use an exact local role embedded in `source` and state a
|
|
unique match:
|
|
|
|
```json
|
|
{
|
|
"kind": "face",
|
|
"source": "front_hub_boss.top_planar_face",
|
|
"match": "unique"
|
|
}
|
|
```
|
|
|
|
Do not add `role`, `query`, `host_face`, a face index, a coordinate selector,
|
|
or a Runtime selector token. The `source` value is the complete local intent.
|
|
The compiler adds its source feature as an auditable graph dependency; include
|
|
other true construction dependencies in `depends_on` yourself.
|
|
|
|
`top_planar_face` and `end_face` mean the positive-direction cap of a supported
|
|
extrude, sweep, loft, or cylinder. `bottom_planar_face` and `start_face` mean
|
|
the opposite cap. Select the most recent feature whose output is known to be
|
|
the required host; do not select a similar face by location, face index, or
|
|
proximity.
|
|
|
|
Translate a request's descriptive `max_z`/`min_z` wording into these output
|
|
roles before writing CDSL. Never emit `base.max_z_face` or `base.min_z_face`.
|
|
For a cylinder built in `+Z`, the top cap is `top_planar_face` and the bottom
|
|
cap is `bottom_planar_face`; reverse-direction features swap their world-Z
|
|
position but retain their own start/end roles.
|
|
|
|
`hole_wizard` requires exactly one `face` selector. It uses that selector as
|
|
its host face, so a central bore on a hub should select the hub cap, while a
|
|
bolt circle on an exposed flange should select the flange cap. A selector must
|
|
name a host that contains every requested hole position. If that cannot be
|
|
made unique, redesign the feature sequence or omit the unsupported feature;
|
|
never guess a face.
|
|
|
|
Before creating a hosted hole, calculate each position against the actual host
|
|
face. A local boss can be the global highest face while being too small to host
|
|
a larger bolt circle. In that case use the exposed flange cap at the bolt
|
|
radius, with its own plane height, rather than the global maximum-Z cap. Place
|
|
the hosted holes while that source cap's exact provenance is still active:
|
|
before a later fusion or cut would split, remove, or replace it. A final
|
|
through-cut may still follow all additive features, so a bolt circle can be
|
|
hosted before an unrelated final boss and before that final cut.
|
|
|
|
## Acceptance And Repair
|
|
|
|
Describe only user-requested, measurable acceptance targets in
|
|
`acceptance_targets`; leave inferred dimensions in `assumptions`. On repair,
|
|
return a complete replacement document. Preserve feature names and every
|
|
feature listed in `executed_feature_ids`, except a feature explicitly named by
|
|
the diagnostic. Features that were never executed may be changed freely to
|
|
repair an invalid selector, parameter, dependency, or geometry construction.
|
|
|
|
Read structured diagnostics literally. Fix their named cause with the smallest
|
|
document change, then return the entire document. Do not add internal IDs,
|
|
weaken a requested value, silently delete a failed feature, or replace a
|
|
failed selector with an arbitrary topology element.
|