Skip to content
Merged
33 changes: 33 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added

- **`create_sketch` takes `face_point`** (#206): a point in mm on a flat
face of the body, in place of `plane`. The sketch opens on that face and
moves with it when the model changes, so a pocket cut from it follows a
height edited later. Give exactly one of `plane` and `face_point`; a point
in the air or on a curved face fails with `invalid_input`.

### Fixed

Found building the monitor stand demo (#206):

- **`list_features` returns rows in tree order.** When SolidWorks stopped
the forward walk at the system folders, the rest came newest first.
- **`verify_model` counts a plane the agent made.** It skipped the first
three reference planes in row order, so with rows newest first it counted
`Front Plane` and skipped `Plane1`.
- **`list_model_dimensions` lists each dimension once, under its own
feature.** It walks the tree the way `list_features` does, and takes each
dimension's feature from its full name: `D1@Plane1` is listed under
`Plane1`, never also under a cut sketched on that plane.
- **`export_stl` keeps its STL options.** `SaveAs2` was called with six
arguments of the wrong types, so it always failed with a type mismatch
and `SaveAs3` wrote the file without merging the bodies. It now gets its
eight arguments; if it still writes nothing, `SaveAs3` writes the file and
the reply's `warning` says the options weren't applied.

### Changed

- **The monitor stand demo** sketches its pocket on the stand's top face,
with no reference plane, and its camera turns to an isometric view after
each feature (`--look` in the script).

## [2.0.0] - 2026-11-12

### Added
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/assets/progress/progress.json
Original file line number Diff line number Diff line change
Expand Up @@ -440,7 +440,7 @@
"family": "sketching",
"level": "stable",
"reason": "",
"summary": "Open a new sketch on a plane of the active part, ready for lines, circles and other sketch entities."
"summary": "Open a new sketch on a plane or a flat face of the active part, ready for lines, circles and other sketch entities."
},
{
"name": "create_sweep",
Expand Down
2 changes: 1 addition & 1 deletion docs/assets/progress/tables.html
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@
<tr data-level="stable" data-family="modeling"><td title="Add a reference point on an edge (at a distance or percentage along it) or at the centre of a face."><code>create_reference_point</code></td><td>modeling</td><td><span class="level level-stable">stable</span></td><td>Add a reference point on an edge (at a distance or percentage along it) or at the centre of a face.</td></tr>
<tr data-level="stable" data-family="modeling"><td title="Revolve a closed sketch around an axis, adding a solid to the active part."><code>create_revolve</code></td><td>modeling</td><td><span class="level level-stable">stable</span></td><td>Revolve a closed sketch around an axis, adding a solid to the active part.</td></tr>
<tr data-level="planned" data-family="drawing"><td title="Cut a section view along a line across a drawing view."><code>create_section_view</code></td><td>drawing</td><td><span class="level level-planned">planned</span><br><small>no adapter implements it yet.</small></td><td>Cut a section view along a line across a drawing view.</td></tr>
<tr data-level="stable" data-family="sketching"><td title="Open a new sketch on a plane of the active part, ready for lines, circles and other sketch entities."><code>create_sketch</code></td><td>sketching</td><td><span class="level level-stable">stable</span></td><td>Open a new sketch on a plane of the active part, ready for lines, circles and other sketch entities.</td></tr>
<tr data-level="stable" data-family="sketching"><td title="Open a new sketch on a plane or a flat face of the active part, ready for lines, circles and other sketch entities."><code>create_sketch</code></td><td>sketching</td><td><span class="level level-stable">stable</span></td><td>Open a new sketch on a plane or a flat face of the active part, ready for lines, circles and other sketch entities.</td></tr>
<tr data-level="stable" data-family="modeling"><td title="Sweep a closed profile sketch along a path sketch to make a solid (Insert &gt; Boss/Base &gt; Sweep)."><code>create_sweep</code></td><td>modeling</td><td><span class="level level-stable">stable</span></td><td>Sweep a closed profile sketch along a path sketch to make a solid (Insert &gt; Boss/Base &gt; Sweep).</td></tr>
<tr data-level="stable" data-family="drawing"><td title="Place a model&#x27;s three standard views (front, top and side) on the active drawing sheet in one call."><code>create_technical_drawing</code></td><td>drawing</td><td><span class="level level-stable">stable</span></td><td>Place a model&#x27;s three standard views (front, top and side) on the active drawing sheet in one call.</td></tr>
<tr data-level="planned" data-family="automation"><td title="Create a part, assembly or drawing template file (.prtdot, .asmdot, .drwdot) with standard settings."><code>create_template</code></td><td>automation</td><td><span class="level level-planned">planned</span><br><small>no adapter implements it yet.</small></td><td>Create a part, assembly or drawing template file (.prtdot, .asmdot, .drwdot) with standard settings.</td></tr>
Expand Down
21 changes: 11 additions & 10 deletions docs/demos.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,8 +146,9 @@ powershell -ExecutionPolicy Bypass -File tests\scripts\live_demo.ps1 `

The recording opens on the prompts, then replays the build as the script
below runs it, at the sizes the stand was finished at by hand (see
"Finished by hand"): 24 tool calls, each captioned with its result, and the
finished part in an isometric view. It is sped up five times.
"Finished by hand"): 23 tool calls, each captioned with its result. The
camera turns to an isometric view after the block, each cut, the arches and
the pocket, so each feature shows as it is made. It is sped up five times.

**Printed.** The finished stand on the printer, in PETG, printed on its side
with tree supports (sped up):
Expand Down Expand Up @@ -281,16 +282,16 @@ the same legs, arches and pocket outline, cut 11.46 mm deep, comes to
901 762 mm³ by hand. SolidWorks measures 901 769 mm³.

The script below was then updated to reproduce this part: 66 mm, a 26 mm
top and an 11.46 mm pocket are its defaults. One thing can't be matched:
the tools can only offset a plane from a named plane, so the script puts
the pocket's plane at Top Plane offset by the height. The solid is the
same, but the plane doesn't follow a height edited by hand. To change the
height, rerun the script.
top and an 11.46 mm pocket are its defaults. It sketches the pocket on the
stand's top face (`create_sketch` with `face_point`), as the user did by
hand, so the pocket follows the height when `D1@Boss-Extrude1` is edited
later, and no reference plane is needed.

**Rebuild it, or at another size.** The script replays the
calls with every dimension an option, and checks the result the same way.
At its defaults it makes the 24 calls in the recording; the session's own
28 calls are listed above.
At its defaults it makes 22 calls, and 23 with `--stl` as in the recording;
the session's own 28 calls are listed above. `--look` turns the camera to
an isometric view after each feature, as the recording does.

```powershell
# The finished stand
Expand All @@ -312,7 +313,7 @@ To record the demo again:

```powershell
powershell -ExecutionPolicy Bypass -File tests\scripts\live_demo.ps1 `
-Test tests/live/test_live_sw_monitor_stand_demo.py `
-Test tests/live/test_live_sw_monitor_stand_demo.py::test_monitor_stand_from_prompt_to_part `
-CaptureDir docs/assets/demos/monitor-stand -Record -PromptSeconds 12
```

Expand Down
20 changes: 15 additions & 5 deletions docs/user-guide/tool-catalog/sketching.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,25 +10,35 @@ Build 2-D sketch geometry (lines, circles, arcs, splines, polygons) and apply ge

### `create_sketch`

Open a new sketch on a plane of the active part, ready for lines, circles and other sketch entities.
Open a new sketch on a plane or a flat face of the active part, ready for lines, circles and other sketch entities.

**Prerequisite:** Active part document, no active sketch

**Parameters:**
**Parameters:** give exactly one of `plane` and `face_point`.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `plane` | `str` | ✅ | `` | Sketch plane name (e.g., 'Top', 'Front', 'Right', 'XY', 'XZ', 'YZ') |
| `sketch_name` | `str?` | — | `None` | Sketch name alias |
| `plane` | `str?` | one of | `None` | Sketch plane name (e.g., 'Top', 'Front', 'Right', 'XY', 'XZ', 'YZ', or a plane made by `create_reference_plane`) |
| `face_point` | `list[float]?` | one of | `None` | `[x, y, z]` in mm on a flat face of the body; the sketch opens on that face and moves with it when the model changes |
| `sketch_name` | `str?` | — | `None` | Name `exit_sketch` gives the sketch when it closes it |

**Sample call:**
A `face_point` that is not on a flat face of the body (in the air, or on a
fillet) fails with `error_type: "invalid_input"` and opens no sketch.

**Sample calls:**

```json
{
"plane": "Front"
}
```

```json
{
"face_point": [0, 20, 0]
}
```

---

### `add_line`
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-12
144 changes: 144 additions & 0 deletions openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
## Context

See proposal.md for the six faults. Where each one comes from:

- **`list_features`' traversal:** the real adapter walks with
`FirstFeature` and `GetNextFeature`, then always adds a
`FeatureByPositionReverse(0..GetFeatureCount(True)-1)` pass. The forward
walk can stop at the system folders. The second pass then finds the
remaining features newest first, and they are appended in that order.
The rows are de-duplicated but never sorted.
- **`verify_model`:** `_count_modelling_features` skips the first three
`RefPlane` rows it meets, in row order. On the monitor stand the rows came
newest first, so it skipped `Plane1`, `Right Plane` and `Top Plane` and
counted `Front Plane` (seen in the session's `verify_model` reply).
- **`list_model_dimensions`:** it has its own forward-only walk, with no
reverse pass, and reads `GetFirstDisplayDimension` on every feature,
folders included. It found 0 with no name on the monitor stand, and all
four when given each feature's name. The same walk serves both calls, so
the cause is not proven. A block's full listing does work live
(`test_dimensions_list_and_measure`).
- **`SaveAs2`:** the installed type library gives `IModelDocExtension.SaveAs2(Name,
Version, Options, ExportData, ReferencePrefixOrSuffixText As String,
AddTextAsPrefix As Boolean, Errors As Long by reference, Warnings As Long by
reference)` (eight arguments; a first live run with seven, leaving out
`Warnings`, failed with "Parameter not optional"). The adapter
calls it with `(path, 0, 2, stl_data, None, "")`.
- **`create_sketch`:** it selects a plane by name (with locale aliases),
then calls `InsertSketch`. Faces are already selected by coordinates
elsewhere, for example `create_reference_plane`'s `face_point` and
`select_face_edges`.

## Goals / Non-Goals

**Goals:**
- Feature and dimension listings that agree with the tree whatever the walk.
- A sketch on a face in one call, through the same adapter path as a plane.
- A demo whose recording shows each feature as it is made.

**Non-Goals:**
- Sketching on a curved face, or on a face of an assembly component.
- Changing `export_stl`'s inputs; only the call underneath changes.
- Finding why `GetNextFeature` stops at the folders. Both passes stay.

## Decisions

### 1. Sort `list_features` rows by tree position, in the adapter

Both passes number features by their place in the top-level tree. The
forward pass counts from 0, and the reverse pass uses
`count - reverse_pos - 1`, so a feature found by both gets the same number.
The adapter sorts each document's rows by `position` before returning
them, keeping each component's rows together as they are now. Every caller
then gets tree order: `verify_model`, the classifier, the bitmap, and
feature-tree diffs.

*Alternative:* sort only in `verify_model`. Rejected: every caller assumes
tree order, and only one has been caught by it.

### 2. `verify_model` skips default planes by position

Once rows are in tree order, the first three `RefPlane` rows are the
defaults. To guard against an adapter that doesn't sort, `verify_model`
also sorts its rows by `position` before counting. This keeps the rule
language-independent, as now: no plane names are matched.

### 3. `list_model_dimensions` walks with `list_features`

The adapter reads the features with the same two-pass traversal as
`list_features` (a shared walk, not a copy), then reads each one's display
dimensions. Folder rows are skipped, as nothing there has dimensions. Each
dimension is kept once, keyed by `full_name`, with `feature` set from the
part after `@`. With `feature_name`, the result keeps the dimensions whose
`feature` matches. A sketch's own dimensions (`D1@Sketch3`) keep the sketch
as their feature, so asking for the cut no longer returns the plane's offset.

*Live diagnostic:* a test builds the monitor stand at its defaults and
records, for the old and new walks, how many features each finds and how
many dimensions each lists. This proves the fix and explains the 0.

### 4. `SaveAs2` with its eight arguments

`ext.SaveAs2(path, 0, swSaveAsOptions_Silent, stl_data, "", False, errors, warnings)`
with `errors` and `warnings` by-reference Longs (`_byref_long`, as `RunMacro2` uses). When
`GetExportFileData` gives nothing, `ExportData` is a `VT_DISPATCH` null.
Success is the file existing. If `SaveAs2` writes nothing, `SaveAs3` runs
as now, and the tool's reply carries a `warning` that the STL options
weren't applied. The first `except` that retried `SaveAs2` without the data
goes: it was a second copy of the same wrong call.

### 5. `create_sketch(face_point=...)`

The input model takes exactly one of `plane` and `face_point`. Today `plane`
is required, so it becomes optional with the one-of check, and the error
names both. The adapter method gains `face_point: tuple[float, float, float]
| None`, through every adapter layer. The real adapter:

1. finds and selects the face with `_select_face_at_point`, the helper
`create_reference_plane`'s `face_point` already uses live: it reads the
body's faces, takes the one whose closest point is within 0.01 mm,
refuses a face with no normal (curved), and selects it with
`IFace2.Select4`. It works from the body's geometry, so it needs neither
`SelectByID2` nor a rebuild first (decided at implementation, replacing
the `SelectByID2` + `IsPlane()` route first planned here);
2. on no face, a curved face or a refused selection, clears the selection
and raises `LookupError("face_point [x, y, z] mm is not on a flat face
of the active part (<reason>)")`. One rule in `error_classifier.py`
matches exactly that message and classifies it `invalid_input`; the
shared "No face found at point" message stays `not_found` for
`select_face_edges`;
3. calls `InsertSketch(True)`, and reads the new sketch's name as the
plane path does.

The mock records the point and answers a point inside its block's top face
(mirroring its existing coordinate model), and refuses others.

*Alternative:* `face_name` (`Face<3>`). Rejected: agents don't know face
names, and every other face input in the tools is a point.

### 6. The demo

`scripts/demo_monitor_stand.py` sketches the pocket with
`create_sketch({"face_point": ...})` on the top face, at the stand's
centre, at its height. `create_reference_plane` drops out of the script.
For the recording, the script turns the camera to isometric and zooms to
fit after each cut and the fillet. It reuses the README demo's `_look`
pattern (`ShowNamedView2("", 7)`, `ViewZoomtofit2`), behind a flag the live
test sets, since it is demo-side COM and not a tool. The GIF is re-recorded
with `SW_DEMO_RECORD`, and the docs page's call list and count are updated.

## Risks / Trade-offs

- [Sorting changes `list_features`' order for callers that relied on the
old order] → Only the broken case changes order: when the forward walk
finishes, the rows are already in tree order. Feature-tree diffs key by
name.
- [`SaveAs2` with the right arguments still fails on some versions] → The
`SaveAs3` fallback stays, now with a `warning`, so no export is lost. The
live test records which path wrote the file.
- [The diagnostic shows the 0 had another cause] → It runs in the bundle.
If the new walk still misses dimensions, that is fixed after the bundle,
one at a time, as agreed.
- [The pocket on the face changes the stand's volume] → No: the face is at
the same height the offset plane was. The live test checks the volume
against the recorded 901 769 mm³.
Loading
Loading