Doni/ModelHandle
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add STEP tree deletion design spec

Browse Source
This commit is contained in:
sladro 2026-04-10 10:57:22 +08:00
parent 0473d9befb
commit 05bc283d59
1 changed files with 250 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

250
docs/superpowers/specs/2026-04-10-step-tree-edit-design.md Normal file
View File

@ -0,0 +1,250 @@
# STEP Tree Deletion And Save Design
## Background
This project already supports:
- Loading and visualizing STEP models in the browser.
- Navigating model hierarchy in the existing tree panel.
- Downloading the original file.
- Exporting display-oriented formats such as OBJ, GLTF, STL, PLY, OFF, 3DM, and BIM.
The requested feature is different from the existing export flow. The new flow must allow the user to:
1. Open a STEP model.
2. Select an assembly node or a leaf part node in the hierarchy.
3. Delete the selected node together with all of its descendants.
4. Save a new `.stp` or `.step` file that reflects the deletion result.
The feature is for demo use. The design should stay simple, stable, and isolated from the current download and export behavior.
## Goals
- Add a minimal deletion flow for STEP hierarchy editing.
- Keep the existing UI mostly unchanged.
- Keep the current `Download` and `Export` behavior unchanged.
- Generate a real new STEP file after deletion.
- Prioritize successful export over full metadata preservation.
## Non Goals
- No drag and drop hierarchy editing.
- No rename, merge, split, or reparent operations.
- No undo stack in the first version.
- No remote backend deployment.
- No attempt to preserve every original STEP attribute if that makes the demo unstable.
## Chosen Approach
Use the current browser UI for selection and preview, and add a small local STEP service for deletion-aware save.
### Why this approach
- The browser side already has the tree, the viewer, and selection behavior.
- The current project can import STEP but cannot write STEP.
- Writing a real STEP file needs CAD-side functionality outside the current browser export pipeline.
- A local service is enough for a demo and avoids introducing a full remote backend.
## User Experience
### Scope
- The feature is only active for `.stp` and `.step` models.
- The user can delete:
- An assembly node.
- A leaf part node.
- Deleting a node removes the whole subtree under that node.
### UI Changes
- Reuse the existing navigator tree.
- Add one deletion action for the current selection:
- Preferred entry: `Delete Selected`.
- Optional secondary entry: tree context menu action if needed later.
- Add one new toolbar action: `Save STEP`.
- Keep the existing `Download` action unchanged.
- Keep the existing `Export` dialog unchanged.
### Interaction Rules
1. The user selects a deletable node from the current hierarchy tree.
2. The user clicks `Delete Selected`.
3. A confirmation dialog asks: `Delete selected node and all its children?`
4. After confirmation:
- The node disappears from the tree.
- The corresponding geometry disappears from the viewer.
5. The user clicks `Save STEP`.
6. The browser downloads a new STEP file generated from the edited hierarchy.
### Reset Behavior
- No undo in the first version.
- Reloading the original file resets the deletion state.
## Architecture
### Frontend Responsibilities
- Detect whether the current model is a STEP model.
- Track deleted hierarchy nodes.
- Update the tree and viewer immediately after deletion.
- Call the local STEP service only for `Save STEP`.
- Leave existing export code paths untouched.
### Local STEP Service Responsibilities
- Accept the original STEP file and the deletion list.
- Reconstruct the export hierarchy from the original file.
- Remove the requested subtrees.
- Write a new STEP file.
- Return the generated file to the browser for download.
### Isolation Rule
The new feature must use its own save path and must not be added into the current generic `ExportDialog`.
This keeps three behaviors separate:
- `Download`: returns the original uploaded file.
- `Export`: converts the current visualization model into the already supported formats.
- `Save STEP`: creates a new STEP file from the deletion result.
## Data Model
### Deletion Representation
Frontend deletion state is stored as a set of stable hierarchy path identifiers.
Each deletable node gets a path-based identifier derived from its position in the tree, for example:
- `0`
- `0/2`
- `0/2/1`
This represents child index traversal from the root and avoids relying on names.
### Why path identifiers
- Runtime `nodeId` values in the viewer are temporary and only valid for the current in-memory import.
- Names are not safe because duplicates are common in CAD assemblies.
- Path identifiers are simple and deterministic for a demo.
### Deletion Semantics
- Deleting a node marks its path as deleted.
- Any child path under a deleted path is implicitly deleted.
- The frontend may prune redundant child deletions when a parent is already deleted.
## Save Flow
1. User opens a STEP file.
2. Frontend builds deletion-capable node metadata for the current tree.
3. User deletes one or more nodes.
4. Frontend updates the visible tree and viewer state.
5. User clicks `Save STEP`.
6. Frontend sends:
- The original STEP file.
- The normalized deleted path list.
7. Local STEP service creates a new STEP file with those paths removed.
8. Browser downloads the returned file.
## Local Service Design
### Recommended Form
- A small local HTTP service running on `127.0.0.1`.
- Implemented in Python for simple scripting and process control.
- Backed by local CAD-capable tooling that can read and write STEP.
### Recommended Backend Choice
Use a local Python-based STEP processing implementation first, with FreeCAD or OCC-backed scripting as the practical demo backend.
Reason:
- It is outside the browser, which is required for real STEP writing.
- It is easier to demo locally than a remote service.
- It keeps the web app changes small.
### API Shape
Keep the API minimal:
- `POST /save-step`
- Multipart form fields:
- `file`: original STEP file
- `deletedPaths`: JSON array of deleted hierarchy paths
- Response:
- Binary STEP file stream
No persistent session is required for the first version.
## Compatibility And Stability Rules
- Only show or enable `Save STEP` when the current file is `.stp` or `.step`.
- Do not change the existing behavior for non-STEP files.
- If the local service is unavailable, show a clear error and keep the current in-browser state intact.
- If saving fails, the deletion preview remains visible so the user can retry.
- The feature should not break the existing viewer even if the local service is not running.
## Error Handling
### Frontend Errors
- No valid selection for deletion:
- Show a small message and do nothing.
- Selected node is not deletable:
- Keep delete action disabled.
- Local service unreachable:
- Show a blocking message that the local STEP save service is not running.
### Save Errors
- Invalid response from local service:
- Show save failure dialog.
- STEP processing failure:
- Show the backend error message if available.
- Empty export result:
- Treat as failure and do not trigger download.
## Testing Strategy
### Manual Demo Tests
1. Load a sample STEP model.
2. Delete a leaf part node.
3. Save a new STEP file.
4. Reopen the generated STEP file and verify the deleted part is missing.
5. Load a sample STEP model again.
6. Delete an assembly branch.
7. Save a new STEP file.
8. Reopen the generated STEP file and verify the whole subtree is missing.
9. Verify `Download` still returns the original uploaded file.
10. Verify the existing `Export` dialog still exports supported non-STEP formats exactly as before.
11. Verify non-STEP models never show an active `Save STEP` action.
### Regression Focus
- Tree deletion must not break mesh visibility toggling.
- Existing selection and fit-to-window behavior must continue to work.
- Existing toolbar actions must not change behavior.
## Implementation Boundaries
- Keep frontend changes focused on the navigator and toolbar integration.
- Do not refactor the current exporter architecture unless required by this feature.
- Do not merge the new save action into the current export dialog.
- Prefer a direct, demo-friendly implementation over generalized framework work.
## Final Decision
Build a minimal STEP subtree deletion demo with:
- Existing viewer and tree as the interaction surface.
- One delete action for the selected node.
- One separate `Save STEP` action.
- One local service dedicated to generating the new STEP file.
This is the shortest path that satisfies the requested workflow without creating conflicts with the current export and download features.