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
24 changes: 24 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
## What changed

<!-- Describe the script or repository change. -->

## User impact

<!-- Explain the Revit workflow and expected result. -->

## Risk and scope

- Catalog risk: <!-- read / write / destructive -->
- Model changes: <!-- none / describe -->
- Intentional exclusions: <!-- describe -->

## Validation

- [ ] `python tools/validate_catalog.py`
- [ ] Tested manually in Revit

Tested Revit versions: <!-- list versions, or state not tested -->

## Documentation

<!-- Link the paired Markdown file and note any catalog changes. -->
25 changes: 25 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
name: Validate script catalog

on:
pull_request:
push:
branches:
- main

permissions:
contents: read

jobs:
validate:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v7

- name: Set up Python
uses: actions/setup-python@v6
with:
python-version: "3.12"

- name: Validate catalog and script syntax
run: python tools/validate_catalog.py
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
__pycache__/
*.py[cod]
.venv/
70 changes: 70 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# Contributing scripts

Contributions should remain easy to run manually through BIMO Run Python and predictable enough for future AI-agent discovery through BIMO MCP.

## Add a script

1. Choose an existing category or create a focused lowercase category folder.
2. Add a descriptively named `lower_snake_case.py` file.
3. Add a Markdown file with the same stem.
4. Register the script in `catalog.json`.
5. Run `python tools/validate_catalog.py`.
6. Describe any Revit testing performed in the pull request. Do not mark an untested version as tested.

Existing files with historical naming are allowed to keep their paths so saved BIMO presets continue to work.

## BIMO script contract

New scripts should:

- declare either `ironpython` or `dynamo-cpython3` in the catalog;
- use BIMO-provided Revit globals only when the selected engine supports them;
- read optional positional values from `IN` and document every index;
- assign a concise value to `OUT` for predictable manual and MCP results;
- validate required selection and inputs before changing the model;
- avoid modal prompts and hidden dependencies when preselection or `IN` can be used;
- open their own Revit transaction for model changes;
- roll back a started transaction when an operation fails;
- allow exceptions to reach BIMO so failed executions are not reported as successful;
- avoid secrets, credentials, machine-specific paths, and unrequested network access.

IronPython scripts intended for BIMO may use these globals:

| Global | Value |
| --- | --- |
| `__doc__` | Active Revit `Document` |
| `__uidoc__` | Active Revit `UIDocument` |
| `__revit__`, `__uiapp__` | Active `UIApplication` |
| `__selection__` | Active Revit selection object |
| `IN` | Positional input list |
| `OUT` | Script result assigned by the script |

## Documentation contract

The paired Markdown file must state:

- purpose and expected user outcome;
- engine and minimum Revit version;
- whether the script reads, writes, or deletes model data;
- active-document and selection requirements;
- every `IN` value, type, order, and default;
- `OUT` format;
- important limitations and a manual Revit test scenario.

## Catalog risk levels

- `read`: inspects model state without intentionally changing it;
- `write`: creates or modifies model state;
- `destructive`: deletes elements or performs changes that are difficult to reverse.

Risk metadata is guidance for users and agents. It does not replace BIMO authorization, code review, backups, or Revit transaction safety.

## Validation

Run:

```shell
python tools/validate_catalog.py
```

The validator checks JSON syntax, required metadata, unique IDs and paths, paired documentation, catalog coverage for every script, and CPython-parsable syntax. It does not execute Revit API code or prove runtime compatibility.
90 changes: 44 additions & 46 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,68 +1,66 @@

![run_python_cover](https://github.com/user-attachments/assets/bfba335f-8ee6-4665-8fc6-f75f4372acd3)
![BIMO Run Python](https://github.com/user-attachments/assets/bfba335f-8ee6-4665-8fc6-f75f4372acd3)

# BIMO Run Python Scripts

Welcome to the **BIMO Revit Python Scripts** repository! This repository is a collection of useful Python scripts designed to work with the **[Run Python](https://bimo.tools/tools?button=runPython)** command in the **[BIMO Add-in](https://bimo.tools)** for Autodesk Revit. The scripts aim to automate routine and complex tasks, streamlining workflows for Revit users.

## 📋 About

The **BIMO Add-in for Revit** includes a powerful **[Run Python](https://bimo.tools/tools?button=runPython)** command, which allows users to execute custom Python scripts within the Revit environment. This repository is intended to provide ready-to-use scripts for various tasks, along with examples to help you write your own.

Feel free to explore the scripts, adapt them to your projects, or contribute by sharing your own scripts!

## 🗂️ Repository Structure
Community-maintained Revit automation scripts for [BIMO Run Python](https://bimo.tools/docs/library/run-python). The repository is designed for both direct use by Revit users and machine discovery by AI agents that execute approved scripts through BIMO MCP.

The scripts in this repository are organized into categories to make it easier to find relevant code for your needs:
## Quick start

- **`wall_scripts/`**: Scripts related to wall management, such as counting walls, calculating wall areas, or modifying wall properties.
- **`door_scripts/`**: Scripts for managing doors, including swing direction checks, door schedules, and door counts.
- **`model_management/`**: Scripts to manage and optimize Revit models, like purging unused elements, auditing models, and adjusting views.
- **`room_scripts/`**: Scripts related to room management, such as calculating room volumes, adjusting room boundaries, and renaming rooms.
- **`miscellaneous/`**: Various scripts for tasks not covered in the other categories.
1. Download or clone this repository.
2. In Revit, open **BIMO > Run Python** and create a preset.
3. Select the engine declared for the script in [`catalog.json`](catalog.json).
4. Leave the inline **Script** field empty and set **Script file** to the `.py` file.
5. Add the documented `IN` values, prepare the required selection, and run the preset.

Each folder contains a README file with specific instructions on how to use the scripts in that category.
BIMO hosts the Python engine inside Revit, so users do not need a separate local Python installation just to run these scripts. Scripts that modify a model manage their own Revit transactions.

## 🛠️ How to Use the Scripts
## Script catalog

### Requirements
| Script | Category | Engine | Risk |
| --- | --- | --- | --- |
| [Create Toposolid from model lines](modeling/create_toposolid_from_model_lines.md) | Modeling | IronPython | Writes model |
| [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 |

- Autodesk Revit with the **BIMO Add-in** installed.
- Python installed on your system (if you plan to write your own scripts).
The authoritative machine-readable index is [`catalog.json`](catalog.json). Its contract is defined by [`schemas/catalog.schema.json`](schemas/catalog.schema.json).

### Running a Script
## Repository structure

1. Open Autodesk Revit.
2. Go to the **BIMO** tab on the Revit toolbar.
3. Click the **[Run Python](https://bimo.tools/tools?button=runPython)** button.
4. From the dropdown menu, select the Python script you want to execute (or load a new script from your computer).
5. Click **OK** to run the script and view the results.
```text
catalog.json Machine-readable script index
schemas/catalog.schema.json Catalog JSON Schema
modeling/ Model-creation and editing scripts
miscellaneous/ General-purpose scripts
tools/validate_catalog.py Dependency-free repository validator
.github/workflows/ Continuous validation
```

### Example Scripts
Every executable script has a paired Markdown file explaining selection requirements, inputs, output, supported Revit versions, and model-change risk. Existing script paths are kept stable so saved BIMO presets do not break.

Here are some example scripts you can start with:
## Using the catalog from an AI agent

1. **Count Walls**: Counts the total number of walls in the active model.
2. **Door Swing Direction**: Checks the swing direction of all doors and stores the result in the door's parameters.
3. **Purge Unused Elements**: Cleans up the Revit model by purging unused families, materials, and styles.
An agent should:

## 🤝 Contributing
1. Filter `catalog.json` by category, tags, engine, Revit version, and risk.
2. Read the script documentation before execution.
3. Confirm required selection and inputs.
4. Treat `write` and `destructive` scripts as model-changing operations requiring explicit approval.
5. Load the exact file referenced by `path` and execute it through the supported BIMO Run Python or MCP operation.
6. Return the script's `OUT` value or execution error without claiming success before Revit confirms it.

We welcome contributions from the community! If you have a useful script that you'd like to share, please follow these steps:
The catalog helps discovery; it is not an execution allowlist or a security boundary. Review scripts before running them and use a test model for model-changing operations.

1. Fork the repository.
2. Create a new branch (`git checkout -b your-feature-branch`).
3. Add your script in the appropriate folder.
4. Commit your changes (`git commit -m 'Add new Python script'`).
5. Push to the branch (`git push origin your-feature-branch`).
6. Open a pull request and provide a brief description of your script.
## Contributing

## 💬 Support
See [CONTRIBUTING.md](CONTRIBUTING.md) for the script contract and submission checklist. Validate changes locally with:

If you encounter any issues or have questions about the scripts, feel free to open an issue in the GitHub repository or reach out to the community for support.
```shell
python tools/validate_catalog.py
```

For more information on the **BIMO Add-in**, visit the [BIMO Tools website](https://bimo.tools).
The same check runs in GitHub Actions.

## 📜 License
## License

This repository is licensed under the [MIT License](LICENSE).
Distributed under the [MIT License](LICENSE).
Loading