AGENT SKILL

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

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 — NEVER blenderbim.bim.module.drawing Dependencies: bonsai-core-architecture (Bonsai tool/core/operator pattern)

1. Critical Warnings

  • ALWAYS use bonsai.bim.module.drawing — NEVER use blenderbim.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=True or 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 IfcAnnotation entity in an IfcGroup
  • Properties in EPset_Drawing property set:
    • TargetView — one of the five view types
    • Scale — diagram scale (e.g., "1:100")
    • HumanScale — display string for scale
    • HasUnderlay — render-based background image toggle
    • HasLinework — vector line drawing toggle
    • HasAnnotation — 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_hint maps to building storey index
  • SECTION_VIEW / ELEVATION_VIEW: location_hint represents direction (N/S/E/W)
  • MODEL_VIEW: location_hint is 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 image
  • has_linework — vector line drawing
  • has_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:

  1. Titleblock Processing: embeds titleblock SVG, applies geolocation data
  2. Drawing Integration: embeds drawing SVGs with style isolation via ensure_drawing_unique_styles() (prefixes CSS classes), applies clipping paths
  3. 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) or VIEWPORT (viewport shading)
  • raster_style: JSON-formatted render configuration string

9. Reference Files

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

lagzgabrielmuller-dot
lagzgabrielmuller-dot/kit-ingenieria-3d

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).

★ 0
lagzgabrielmuller-dot
lagzgabrielmuller-dot/kit-ingenieria-3d

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.

★ 0
lagzgabrielmuller-dot
lagzgabrielmuller-dot/kit-ingenieria-3d

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.

★ 0
lagzgabrielmuller-dot
lagzgabrielmuller-dot/kit-ingenieria-3d

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.

★ 0
lagzgabrielmuller-dot
lagzgabrielmuller-dot/kit-ingenieria-3d

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.

★ 0
lagzgabrielmuller-dot
lagzgabrielmuller-dot/kit-ingenieria-3d

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.

★ 0