# CAD Feature Tree Export

`feature_tree.json` is now a SolidWorks FeatureManager-style export. Semantic
models are replayed from the feature nodes themselves; uploaded STEP models use
a SolidWorks-style imported feature with an embedded SurfaceIR payload.

## Contract

- The artifact name stays `feature_tree.json`.
- `tree_kind` is `solidworks_feature_manager`.
- `schema_version` is `1.0`.
- The JSON Schema lives at
  `designir-pipeline/contracts/feature_tree.schema.json`.
- Studio records the artifact with role `feature_tree`; no feature-tree UI is
  required.

Top-level fields are:

- `model`: part metadata such as model id, family, units, and document type.
- `source`: DesignIR path, STEP path, reconstruction mode, backend, and the
  native-history claim.
- `feature_manager`: root id, standard SolidWorks reference nodes, and ordered
  feature nodes.
- `rebuild_contract`: the replay mode and compiler entrypoint.
- `validation`: structure validation, replay status, geometry/B-Rep status, and
  feature-recognition coverage.

## FeatureManager Style

Every tree starts with a familiar part root and reference geometry:

- `历史`
- `原点`
- `前视基准面`
- `上视基准面`
- `右视基准面`
- `原点`

Semantic DesignIR features are normalized into SolidWorks-style nodes:

- `extrude_circle`, `extrude_rectangle`, `add_cylinder` -> `BossExtrude`
- `through_hole` -> `CutExtrude`
- `polar_hole_pattern` -> seed `CutExtrude` plus `CircularPattern`
- recognized future operations map to `Revolve`, `RevolvedCut`, `HoleWizard`,
  `Fillet`, `Chamfer`, `LinearPattern`, and `MirrorPattern`

Parameters are attached to the owning feature node. They are not top-level
tree nodes. Each parameter keeps a `binding_id` that matches `parameters.json`
and the DesignIR semantic parameter name.

Semantic feature trees do not embed a full DesignIR copy. `BossExtrude`,
`CutExtrude`, and `CircularPattern` nodes store the reconstructable sketch,
depth, direction, hole, and pattern definitions needed by the
FeatureTreeCompiler.

Each node also includes SolidWorks-style inspection fields:

- `definition`: feature-specific definition such as end condition, depth,
  direction, merge result, seed features, axis, or sketch profile.
- `dimensions`: SolidWorks-style dimension rows such as `D1@凸台-拉伸1`, with
  parameter bindings when available.
- `references`: sketch, plane, parent features, and child features.
- `selection_sets`: selected faces, edges, and contours. These stay empty until
  stable B-Rep selectors are available.
- `rebuild`: suppression and rollback/rebuild status.

## STEP And SurfaceIR

STEP does not contain original SolidWorks sketches or FeatureManager history.
For uploaded STEP/SurfaceIR models, the exporter creates one canonical
SolidWorks-style imported feature:

- `solidworks_type`: `ImportedFeature`
- `display_name`: `导入1`
- `english_name`: `Imported1`

The imported feature embeds compressed `gzip+base64+json` SurfaceIR. This keeps
the tree honest and independently replayable without pretending that the
original native CAD history was recovered.

## Replay

The tree can be replayed without sibling files:

```bash
python designir-pipeline/scripts/feature_tree.py compile \
  feature_tree.json \
  --output-step replayed.step \
  --output-designir replayed.designir.json
```

Semantic trees replay through `feature_tree.compile_feature_manager`, which
builds DesignIR 3.0 from FeatureManager nodes and then calls
`designir_pipeline.compile_designir`. Imported SurfaceIR trees replay through
`surfaceir_pipeline.build_surfaceir`.