Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ BIMO hosts the Python engine inside Revit, so users do not need a separate local
| [Import image to active view](documentation/import_image_to_active_view.md) | Documentation | IronPython | Writes model and optionally copies a file |
| [Create Toposolid from model lines](modeling/create_toposolid_from_model_lines.md) | Modeling | IronPython | Writes model |
| [Create model-line contour from linked STL slice](modeling/create_model_line_contour_from_linked_stl_slice.md) | Modeling | IronPython | Writes model and optionally reads local assemblies |
| [Create Floors from shape-edited roofs](modeling/create_floors_from_roofs.md) | Modeling | IronPython | Writes model; dry run by default |
| [Calculate selected lines length](miscellaneous/calculate_selected_lines_length_mm.md) | Miscellaneous | IronPython | Read-only |
| [Calculate element volume](miscellaneous/calculate_element_volume.md) | Miscellaneous | IronPython | Read-only |
| [Delete BIMO preview rays](miscellaneous/Delete_BIMO_PreviewRays_DirectShapes.md) | Miscellaneous | IronPython | Deletes elements |
Expand Down
50 changes: 50 additions & 0 deletions catalog.json
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,56 @@
"stl"
]
},
{
"id": "modeling.create-floors-from-roofs",
"name": "Create Floors from shape-edited roofs",
"summary": "Creates validated Floors with roof layers, shape elevations and vertical openings while retaining source roofs and annotations.",
"category": "modeling",
"path": "modeling/create_floors_from_roofs.py",
"documentation": "modeling/create_floors_from_roofs.md",
"engine": "ironpython",
"revit": {
"minimum": 2024,
"tested": []
},
"risk": "write",
"requiresActiveDocument": true,
"selection": {
"required": false,
"description": "Select supported shape-edited Basic FootPrintRoofs, or provide an explicit comma-separated roof ID list in IN[1]. Mixed or empty selections are rejected."
},
"inputs": [
{
"index": 0,
"name": "dry_run",
"type": "boolean-string",
"required": false,
"default": "true",
"description": "Create and validate trial Floors, then roll back everything. Set false to retain the new Floors."
},
{
"index": 1,
"name": "roof_ids",
"type": "string",
"required": false,
"default": "",
"description": "Comma-separated positive roof IDs in the active document; overrides selection. Empty uses current selection."
}
],
"output": {
"format": "object",
"description": "Dry-run state, Floor count, source/target IDs, opening mapping, geometry measurements, point corrections and warnings. Trial IDs are not persistent."
},
"tags": [
"roof",
"floor",
"conversion",
"slab-shape",
"slope",
"opening",
"selection"
]
},
{
"id": "miscellaneous.calculate-selected-lines-length-mm",
"name": "Calculate selected lines length in millimetres",
Expand Down
76 changes: 76 additions & 0 deletions docs/decisions/0002-roof-to-floor-conversion.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# 0002 — Roof-to-Floor geometry conversion

- Status: Accepted for the current draft
- Date: 2026-09-14
- Related issue: [#6](https://github.com/BIMO-Tools/Revit-Python-Scripts/issues/6)
- Implementation: [create_floors_from_roofs.py](../../modeling/create_floors_from_roofs.py)
- User guide: [Create Floors from roofs](../../modeling/create_floors_from_roofs.md)

## Goal and invariants

Reuse a conversion developed through BIMO MCP to create native editable Floors
from shape-edited Basic Roofs. Preserve the existing surface, compound layers,
levels, inner sketch contours and vertical hosted openings. Require explicit
selection or IDs, retain originals and annotations, and roll back the entire
batch if an API operation or geometry check fails.

## Evidence from the original Revit 2024 prototype

The prototype created 16 Floors from 16 Basic FootPrintRoofs of one RoofType with
a 152.4 mm constant structural layer. Six hosted Opening Cuts were recreated;
one additional opening was an inner sketch loop. The largest Opening Cut had
75 straight boundary curves. The source included boundary/edge vertices and
both user-drawn and automatic creases.

A removal trial revealed 45 dependent Spot Slopes, 186 automatic sketch
dimensions and one alignment constraint. That trial was rolled back. Final
creation kept every source and annotation; the user subsequently removed the
sources manually. The reusable script deliberately has no deletion mode.

## Evaluated approaches and decisions

| Approach | Evidence | Decision |
| --- | --- | --- |
| Recreate sketch, shape points, non-boundary creases and hosted openings | Reproduced the prototype geometry as native Floors | Retained; copy automatic creases as explicit split lines to constrain triangulation |
| Boolean symmetric difference of source and result | Revit failed on the complex trimmed main roof | Not the acceptance check; do not infer equivalence from boolean failure |
| Raw mesh vertices and triangle points | Apparent deviations around 0.009 mm despite matching volumes and areas; coordinates far from origin lose mesh precision | Use exact edge samples and project triangle interior points onto analytical source faces |
| Preserve all stored subelement heights literally | A nearly coplanar quadrilateral differed by about 0.02 mm after reconstruction; its stored points did not lie on the source's actual planar face | Match the actual single top-face plane with a bounded, reported correction |
| Implicitly delete original hosts after successful conversion | Would also delete 45 user annotations and an alignment | Retain all sources; deletion is a separate user decision |

The single-plane correction adjusted one prototype's stored height by at most
0.0312993 mm. After correction and precise sampling, maximum sampled surface
distance across all 16 pairs was approximately `5.2e-11 mm`. The affected roof's
relative volume difference was `2.1026e-7`; the other pairs were around floating
point precision. The volume and area acceptance tolerance is `1e-6` relative
with an absolute `1e-6` native-unit floor. Surface tolerance remains 0.01 mm.
These checks are measured practical acceptance criteria, not a mathematical
proof of identical solids.

## API details and retained behaviour

- For the exercised shape-edited roofs, the sketch/base is below the original
flat top by the compound thickness. Floor level offset includes that thickness.
- Get the FootPrintRoof sketch through its dependent `Sketch`; the Revit 2024
FootPrintRoof does not expose the Floor-style `SketchId` property.
- Create missing shape points on the initially flat Floor top. Draw split lines,
then set vertex offsets relative to the initial top elevation.
- `Document.NewOpening(host, curves, False)` cuts vertically. `True` means
perpendicular to the host face, not vertical.
- The BIMO IronPython execution used here did not provide the `traceback` standard
library module. The catalog script uses ordinary re-raising after rollback so
BIMO captures the real exception and reports failure.
- The generalized script derives floor types per source RoofType and uses
explicit selection/IN, replacing all prototype-specific document names and IDs.

## Validation boundary and remaining cases

The measurements above describe the original live prototype. The exact generalized
catalog file needs its own runtime validation; record those results separately
in the PR and only then list a tested Revit version in the catalog.

The script excludes curved faces/boundaries, variable layers, extruded and curtain
roofs, non-shape-edited slopes, shaft openings and hosted-family conversion.
Multiple RoofTypes, additional constant layers, phases, and other Revit versions
need dedicated fixtures. Samples do not exhaust every point on a face, and merged
multi-solid geometry can still encounter Revit boolean-union failures; such a
failure aborts instead of bypassing validation.
1 change: 1 addition & 0 deletions docs/decisions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,4 @@ Update an existing record when its accepted decision is refined. If a decision i
| Record | Status | Scope |
| --- | --- | --- |
| [0001 — Linked STL slice contour extraction](0001-linked-stl-slice-contour.md) | Accepted for the current draft | Exterior model-line contour from a horizontal linked-STL section |
| [0002 — Roof-to-Floor conversion](0002-roof-to-floor-conversion.md) | Accepted for the current draft | Native Floors preserving roof shape and openings |
122 changes: 122 additions & 0 deletions modeling/create_floors_from_roofs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
# Create Floors from shape-edited roofs

Creates one native architectural `Floor` for each explicitly selected Basic Roof,
with its layers, elevation, shape points, split lines, sketch holes and hosted
vertical openings. Source roofs and their annotations are retained.

## Compatibility and scope

- BIMO engine: **IronPython**; minimum Revit API version: **2024**.
- Active editable project required, with no transaction already open.
- Exact catalog-script Revit testing: pending; see the pull request for current results.
- Only `FootPrintRoof` elements with enabled slab-shape editing, straight sketch
and opening boundaries, planar solid faces, and no variable-thickness layer.
- Requires at least one architectural `FloorType` in the project.

The script does not convert extruded/curtain roofs, sloped roof sketches without
shape editing, curved boundaries, variable-layer roofs, shaft openings, or other
hosted families. Later Revit versions are not validated.

## Inputs

BIMO passes optional positional inputs as strings.

| Index | Name | Type | Default | Meaning |
| --- | --- | --- | --- | --- |
| `IN[0]` | `dry_run` | boolean-string | `true` | `true` creates and checks trial elements, then rolls everything back; `false` keeps the new Floors. |
| `IN[1]` | `roof_ids` | string | empty | Comma-separated positive roof IDs in the active document. Empty uses the current selection. |

Every selected or specified element must be a supported roof. Invalid IDs and
mixed selections fail before model changes. An explicit ID list overrides the
selection. Empty input does **not** collect every roof in the project.

## Run through BIMO

1. Select the roofs to convert, or provide their IDs in `IN[1]`.
2. Choose **IronPython**, leave the inline Script field empty and point Script
file at `create_floors_from_roofs.py`.
3. Run with `IN[0] = "true"`. Check the returned geometry report and warnings.
4. Run with `IN[0] = "false"` to retain the new Floors.
5. Inspect the results before manually removing any source roofs. Deleting a
roof can also delete dimensions, spot slopes, alignments and hosted elements.

The same source works through the approved BIMO MCP Python execution operation.
No local Python installation or third-party geometry package is required in Revit.

## Model changes and other side effects

- Creates one Floor per source roof and one new FloorType per distinct RoofType
per run. Copies the compound structure, including layer materials and thicknesses.
- Derives the new type from the lowest-ID architectural FloorType. Uncopied type
properties retain that template's values. Existing types are never modified;
a numeric suffix resolves name collisions.
- Keeps the roof's base level. Sets the Floor offset to the roof base offset plus
the compound-structure thickness, then transfers shape elevations.
- Copies instance comments, mark, creation phase and demolition phase when set
and writable. Other instance/type/shared parameters, worksets, design options,
joins, attachments, hosted families, constraints and view overrides are not copied.
- Recreates curve-based hosted openings as **vertical** Floor openings and
preserves inner sketch loops. Perpendicular openings are not a supported input;
geometric mismatch causes rollback.
- Preserves both user-drawn and automatic non-boundary creases as explicit Floor
split lines, which may change the later editing behaviour of automatic folds.
- Never deletes or modifies source roofs or their dependent annotations, and does
not rehost spot slopes. Source and converted geometry overlap until the user
removes or otherwise manages the sources.
- Does not save, synchronize or close the project, change selection or views,
read/write files, access the network or show its own modal prompts.
- Warnings are collected in `OUT`; errors roll back the entire batch and propagate
to BIMO. A committed run is grouped into one Revit Undo operation.
- Repeating a committed run creates additional Floors and types. It is not an
update or duplicate-detection command.

## Geometry validation

The script compares bidirectional surface samples, solid volumes and total face
areas, including opening surfaces. It checks again after transaction commit and
before accepting the transaction group. Surface sampling is a practical check,
not a proof of exact solid equivalence.

- Maximum sampled surface distance: **0.01 mm**.
- Maximum volume difference: the greater of `1e-6 ft3` or `1e-6` of source volume.
- Maximum area difference: the greater of `1e-6 ft2` or `1e-6` of source surface area.
- Shape-point matching tolerance: `1e-6 ft`.

For a single planar top face, stored shape points may differ slightly from the
actual Revit surface. The script projects their heights onto that plane, reports
the adjustment, and rejects adjustments over **0.1 mm**. It preserves the existing
surface geometry rather than insisting on those inconsistent stored heights.

See [the algorithm decision record](../docs/decisions/0002-roof-to-floor-conversion.md)
for the reason for these checks and prototype measurements.

## Output

`OUT` is an object with `dry_run`, `floor_count`, `created_ids_are_persistent`,
`source_roofs_retained`, `warnings` and a per-roof `report` containing:

- source roof and new Floor IDs, plus source/target opening IDs;
- shape-vertex and explicit split-line counts;
- sampled surface distance and sample count;
- source/result volumes in cubic feet and their difference;
- source/result surface areas in square feet;
- vertex matching error and stored-point adjustment in millimetres.

In a dry run, `floor_count` means successfully validated trial Floors. Their IDs
and opening IDs are **not persistent** after rollback. Failures are execution
errors, never successful results containing `ok: false`.

## Manual Revit test scenario

Use a separate test copy containing several shape-edited polygonal roofs, an inner
sketch hole, vertical Opening Cuts crossing the outer boundary, edge points and
split lines. Include a nearly coplanar quadrilateral and spot-slope annotations.

1. Record counts of Floors, FloorTypes, roofs, openings and spot dimensions.
2. Run dry mode and confirm every count is unchanged.
3. Run commit mode and confirm one Floor per roof, one type per RoofType, and the
expected new opening count; original roofs and annotations must remain.
4. Inspect top/bottom geometry, slope direction, thickness, materials and openings.
5. Test empty/mixed selection and missing IDs; expect an error with no new elements.
6. Exercise multiple RoofTypes and a deliberately unsupported input. Additional
layers, phase transfer and failure-processor error rollback require separate cases.
Loading
Loading