bonsai-impl-drawing
Use when generating 2D drawings from IFC models in Bonsai -- plans, sections, elevations, annotations, or sheet layouts. Prevents the common mistake of creating views without proper drawing style configuration (getting empty or unfiltered output). Covers the complete documentation pipeline from model views through annotations to printable SVG sheet output. Keywords: drawing, plan, section, elevation, annotation, sheet, SVG, titleblock, documentation, 2D drawing, Bonsai drawing, create floor plan, generate section view, print drawings.
- License 许可
- MIT
- 最近更新
- 2026-11-09
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- bonsai-impl-drawing
- license
- MIT
- metadata
- { "author": "OpenAEC-Foundation", "version": "1.0" }
- description
- Use when generating 2D drawings from IFC models in Bonsai -- plans, sections, elevations, annotations, or sheet layouts. Prevents the common mistake of creating views without proper drawing style configuration (getting empty or unfiltered output). Covers the complete documentation pipeline from model views through annotations to printable SVG sheet output. Keywords: drawing, plan, section, elevation, annotation, sheet, SVG, titleblock, documentation, 2D drawing, Bonsai drawing, create floor plan, generate section view, print drawings.
- compatibility
- Designed for Claude Code. Requires Python 3.x.
02 资源文件 3
- 参考文档references/anti-patterns.md7.9 KB
- 参考文档references/examples.md6.9 KB
- 参考文档references/methods.md10.6 KB
03 SKILL.md 正文
Bonsai Drawing and Documentation: Implementation Guide
Version: Bonsai v0.8.x | Blender 4.2+ | Python 3.11 Module path:
bonsai.bim.module.drawing— NEVERblenderbim.bim.module.drawingDependencies: bonsai-core-architecture (Bonsai tool/core/operator pattern)
1. Critical Warnings
- ALWAYS use
bonsai.bim.module.drawing— NEVER useblenderbim.bim.module.drawing(legacy name) - ALWAYS activate a drawing camera before calling
bim.create_drawing - NEVER edit generated SVG files directly — ALWAYS modify annotations in Blender and regenerate
- ALWAYS install InkScape before using sheet composition or PDF export
- Annotations are ONLY generated for orthographic camera views — NEVER for perspective views
- ALWAYS sync IFC data before generating drawings (
sync=Trueor save first) - ALWAYS use project-relative paths for titleblock SVG templates
2. Architecture Overview
The drawing module follows Bonsai's core/tool/operator pattern:
bonsai/core/drawing.py → Pure logic (no Blender imports)
bonsai/tool/drawing.py → Blender-specific implementation
bonsai/bim/module/drawing/
├── operator.py → 40+ Blender operators
├── prop.py → Property definitions
├── ui.py → Panel UI
├── annotation.py → Annotator class (geometry creation)
├── svgwriter.py → SvgWriter class (SVG engine)
├── sheeter.py → SheetBuilder class (sheet composition)
├── decoration.py → Viewport decorations
├── gizmos.py → Interactive annotation gizmos
├── handler.py → Event handlers
├── helper.py → Utilities (format_distance, BoundingBox)
├── scheduler.py → Schedule/table generation
├── shaders.py → GPU shaders for viewport
├── workspace.py → AnnotationTool workspace + keymaps
└── data.py → Data loading and caching
3. Drawing Types Decision Tree
What type of drawing do you need?
│
├─ Floor plan (top-down view) → target_view="PLAN_VIEW"
├─ Vertical section (cut through) → target_view="SECTION_VIEW"
├─ Facade/external view → target_view="ELEVATION_VIEW"
├─ Reflected ceiling plan → target_view="REFLECTED_PLAN_VIEW"
└─ 3D perspective/axonometric → target_view="MODEL_VIEW"
Each drawing is backed by:
- An
IfcAnnotationentity in anIfcGroup - Properties in
EPset_Drawingproperty set:TargetView— one of the five view typesScale— diagram scale (e.g., "1:100")HumanScale— display string for scaleHasUnderlay— render-based background image toggleHasLinework— vector line drawing toggleHasAnnotation— annotation overlay toggle
4. Complete Drawing Pipeline
4.1 Step 1: Create a Drawing
# Bonsai v0.8.x: Add a plan view drawing
import bpy
bpy.ops.bim.add_drawing(
target_view="PLAN_VIEW",
location_hint=0 # 0 = auto-detect from active storey
)
Location hint rules:
PLAN_VIEW/REFLECTED_PLAN_VIEW:location_hintmaps to building storey indexSECTION_VIEW/ELEVATION_VIEW:location_hintrepresents direction (N/S/E/W)MODEL_VIEW:location_hintis ignored
Core function (bonsai/core/drawing.py):
# Bonsai v0.8.x: add_drawing creates:
# 1. Unique drawing name from target_view
# 2. Camera matrix from target_view + location_hint
# 3. IfcAnnotation via ifcopenshell.api.run("root.create_entity")
# 4. IfcGroup for annotations
# 5. IfcDocumentReference to SVG output path
# 6. EPset_Drawing properties (TargetView, Scale, etc.)
# 7. Blender camera object assigned to collection
4.2 Step 2: Configure Camera Properties
# Bonsai v0.8.x: Camera/drawing configuration
# Access via camera object's BIMCameraProperties
# Scale options (metric):
# 1:5000, 1:2000, 1:1000, 1:500, 1:200, 1:100, 1:50,
# 1:20, 1:10, 1:5, 1:2, 1:1, CUSTOM
# Custom scale: custom_scale_numerator / custom_scale_denominator
# Camera type: ORTHO (orthographic) | PERSP (perspective)
# Raster resolution: raster_x, raster_y (default 1000 px each)
# DPI: default 75
# View dimensions: width, height (default 50 m each)
# NTS flag: is_nts (Not To Scale)
Layer toggles (control what the drawing contains):
has_underlay— render-based background imagehas_linework— vector line drawinghas_annotation— annotation overlays
Filter mode: NONE or include/exclude filter groups for element visibility control.
4.3 Step 3: Add Annotations
# Bonsai v0.8.x: Add annotations to the active drawing
import bpy
# PREREQUISITE: MUST have active drawing (camera view)
# Add a text annotation
bpy.ops.bim.add_annotation(object_type="TEXT")
# Add a dimension with type reference
bpy.ops.bim.add_annotation(
object_type="DIMENSION",
relating_type_id=42 # IFC ID of annotation type
)
Supported annotation types:
| Type | Description | Blender Data |
|---|---|---|
TEXT |
Text labels | Mesh |
TEXT_LEADER |
Text with leader line | Curve |
DIMENSION |
Linear dimensions | Mesh |
ANGLE |
Angular dimensions | Mesh |
SECTION_LEVEL |
Section cut markers | Mesh |
PLAN_LEVEL |
Level indicators | Mesh |
ELEVATION |
Elevation markers (SVG symbols) | Mesh |
GRID |
Grid line references | Mesh |
FILL_AREA |
Hatching and fills | Mesh |
STAIR_ARROW |
Stair direction indicators | Mesh |
HIDDEN_LINE |
Hidden/dashed lines | Mesh |
BREAKLINE |
Break line symbols | Mesh |
Text properties (BIMTextProperties):
- Font sizes (mm): 1.8, 2.5, 3.5, 5.0, 7.0
- Horizontal alignment: left, middle, right
- Vertical alignment: top, middle, bottom
- Literals support 16 categories: Basic, Attributes, Property Sets, Material, Task, Cost, etc.
- SVG output supports markdown: bold, italic, links, bullet points
4.4 Step 4: Generate SVG Drawing
# Bonsai v0.8.x: Generate SVG from active drawing
bpy.ops.bim.create_drawing(
sync=True, # Pre-sync IFC data (ALWAYS recommended)
print_all=False, # False = active drawing only; True = all checked drawings
open_viewer=False # Launch viewer after generation
)
SVG generation pipeline:
CreateDrawing Pipeline (bim.create_drawing):
1. Initialize camera and drawing metadata
2. Sync IFC file (if sync=True)
3. Generate UNDERLAY (raster render → PNG → embedded in SVG)
4. Generate LINEWORK (vector):
├─ OPENCASCADE mode → HLR via OCC library (precise, slower)
└─ FREESTYLE mode → Blender Freestyle SVG Exporter (artistic, faster)
5. Generate ANNOTATIONS (via SvgWriter, orthographic only)
6. Combine all SVG layers into final output
Linework mode decision:
| Situation | Use |
|---|---|
| Precise hidden-line removal needed | OPENCASCADE mode |
| Artistic line styles preferred | FREESTYLE mode |
| FREESTYLE mode selected | ALWAYS verify Freestyle SVG Exporter add-on is enabled |
Fill modes (fill_mode): NONE, SHAPELY (polygon fills), SVGFILL (SVG-native patterns)
Cut modes (cut_mode): BISECT (Blender mesh bisect), OPENCASCADE (OCC section cutting)
4.5 Step 5: Compose Sheets
# Bonsai v0.8.x: Sheet composition pipeline
# Step 1: Create sheet with titleblock
bpy.ops.bim.add_sheet()
# Creates IfcDocumentInformation + IfcDocumentReference
# Generates base SVG layout from titleblock template
# Step 2: Add drawings to sheet
bpy.ops.bim.add_drawing_to_sheet()
# Links drawing (IfcDocumentReference) to the sheet
# Step 3: Build final sheet
bpy.ops.bim.create_sheets()
# Composes all drawings into sheet SVG
# Optionally exports to PDF/DXF (requires InkScape)
SheetBuilder (sheeter.py) composition process:
- Titleblock Processing: embeds titleblock SVG, applies geolocation data
- Drawing Integration: embeds drawing SVGs with style isolation via
ensure_drawing_unique_styles()(prefixes CSS classes), applies clipping paths - Document Assembly: incorporates schedules, resolves mustache-syntax template variables
Auto-layout (next_drawing_location()):
- Default start: (30, 30) mm
- Padding: 10 mm between drawings
- Horizontal placement within rows, new row when exceeding titleblock width
- Default titleblock width: 840 mm
4.6 Step 6: Export and Open
# Bonsai v0.8.x: Open generated outputs
bpy.ops.bim.open_drawing() # Open SVG with system viewer
bpy.ops.bim.open_sheet() # Open sheet with system viewer
bpy.ops.bim.open_layout() # Open SVG layout file
5. SVG Coordinate Pipeline
The SvgWriter converts 3D model coordinates to SVG canvas:
3D world coordinates
→ project_point_onto_camera() (plane intersection)
→ camera-space coordinates
→ offset to canvas center, scale by (diagram_scale × 1000)
→ SVG canvas coordinates (millimeters)
Unit conversion: IFC meters → SVG millimeters.
convert_to_mm() normalizes CSS length units (cm, in, pt, px, Q, pc) to millimeters for positioning.
6. Key Operator Reference
| Operator | bl_idname | Purpose |
|---|---|---|
| AddDrawing | bim.add_drawing |
Create new drawing view with camera |
| CreateDrawing | bim.create_drawing |
Generate/refresh SVG |
| DuplicateDrawing | bim.duplicate_drawing |
Copy drawing (optional annotation copy) |
| AddAnnotation | bim.add_annotation |
Add annotation to active drawing |
| AddAnnotationType | bim.add_annotation_type |
Create annotation type template |
| AddSheet | bim.add_sheet |
Create new sheet document |
| CreateSheets | bim.create_sheets |
Build sheets with PDF/DXF export |
| AddDrawingToSheet | bim.add_drawing_to_sheet |
Link drawing to sheet |
| OpenSheet | bim.open_sheet |
Open sheet with viewer |
| OpenDrawing | bim.open_drawing |
Open SVG with viewer |
| OpenLayout | bim.open_layout |
Open SVG layout file |
| ActivateModel | bim.activate_model |
Switch to 3D model view |
| SelectAllDrawings | bim.select_all_drawings |
Batch select drawings |
| SelectAllSheets | bim.select_all_sheets |
Batch select sheets |
7. Annotation Workspace
The AnnotationTool workspace provides dedicated annotation editing:
| Shortcut | Action |
|---|---|
Shift+A |
Add new annotation |
Shift+T |
Bulk tag (auto-adjust to selected objects) |
Shift+G |
Readjust tags based on assigned products |
Shift+E |
Edit text annotations |
8. Drawing Style Configuration
DrawingStyle PropertyGroup controls rendering appearance:
render_type:DEFAULT(Blender render settings) orVIEWPORT(viewport shading)raster_style: JSON-formatted render configuration string
9. Reference Files
- references/methods.md — Complete drawing API signatures
- references/examples.md — Working drawing workflow examples
- references/anti-patterns.md — Drawing anti-patterns and mistakes to avoid
10. Dependencies
- InkScape: REQUIRED for sheet composition and PDF/DXF export
- OpenCASCADE (via ifcopenshell): REQUIRED for OPENCASCADE linework/cut modes
- Shapely: REQUIRED for SHAPELY fill mode and polygon operations
- Freestyle SVG Exporter: REQUIRED when using FREESTYLE linework mode (Blender add-on)
04 同仓库更多 Skills
manimce-best-practices
Trigger when: (1) User mentions "manim" or "Manim Community" or "ManimCE", (2) Code contains `from manim import *`, (3) User runs `manim` CLI commands, (4) Working with Scene, MathTex, Create(), or ManimCE-specific classes. Best practices for Manim Community Edition - the community-maintained Python animation engine. Covers Scene structure, animations, LaTeX/MathTex, 3D with ThreeDScene, camera control, styling, and CLI usage. NOT for ManimGL/3b1b version (which uses `manimlib` imports and `manimgl` CLI).
drawio
Create, edit, replicate, import, and export draw.io diagrams with an offline YAML-first workflow: architecture, network topologies, flowcharts, UML/ER, org charts, Mermaid/CSV conversion, existing .drawio bundles, style presets, themes, and non-publication formula diagrams. For publication figures (paper, thesis, IEEE, camera-ready) use drawio-academic-skills instead.
drawio-academic-skills
Publication-figure overlay for draw.io. Use instead of drawio whenever the diagram is for a paper, thesis, dissertation, journal, conference, IEEE/ACM submission, manuscript, camera-ready, Word/LaTeX figure, or other publication. Applies venue, figure-type, color, caption/legend, formula, and paper-readability gates for architecture, workflow, roadmap, network-topology, and replicated paper figures.
uncertainty-and-units
Tracks physical units and propagates measurement uncertainty in scientific calculations using pint and uncertainties. Use for unit conversion and dimensional checking, GUM uncertainty budgets, Type A and Type B evaluation, coverage factors and expanded uncertainty, Monte Carlo propagation, significant-figure and plus-minus reporting, error propagation through curve fits, CODATA constants, auditing Python code for stripped units or broken uncertainty propagation, and order-of-magnitude plausibility checks using dimensionless groups (Reynolds, Peclet, Damkohler, Knudsen, Biot, Womersley), characteristic scales such as diffusion time or Debye length, and observed magnitude ranges. Trigger on "is this number physically reasonable", "sanity check these units", "what regime is this flow in", or a result that looks off by orders of magnitude.
statistical-analysis
Guided statistical analysis for research data - test selection, assumption checking, effect sizes, power analysis, Bayesian alternatives, and APA-formatted reporting. Use whenever a user wants to compare groups, test a hypothesis, analyze experimental or survey data, check statistical assumptions, compute required sample sizes, or write up results - even if they never name a specific test. Covers t-tests, ANOVA, chi-square, correlation, regression, non-parametric and Bayesian methods. For low-level model APIs, see the statsmodels and pymc skills.
simpy
Builds, inspects, tests, and analyzes bounded process-based discrete-event simulations with SimPy. Use for event scheduling, resource queues, interrupts, monitoring, independent replications, warm-up, and reproducible output analysis.