documents
Views, sheets, schedules, tags, notes, dimensions and the rest of a drawing set.
Every example below is a complete script that passes the kit's checks; the kit's tests run each one.
documents.sheet: A new sheet (number, name, title block); returns its id.documents.setSheet: Changes a sheet's number, name, title block or fields.documents.planView: A floor plan of one level (for a discipline, scale, detailLevel, symbolScale, showLineCodes, and per-category/service overrides including singleLineBelow); returns the view's id.documents.setView: Changes a view's detail level (coarse/medium/fine), visual style, annotativesymbolScale(0.5–3.0), inline service codes, scale, discipline, or per-category/service graphics overrides (including singleLineBelow).documents.ceilingView: A reflected ceiling plan of one level; returns the view's id.documents.sectionView: A vertical building section cut fromfromtoto(direction +1 left / -1 right, depth default 20 ft); supports annotativeheadExt/tailExt, RevitsplitGapbreak, explicitcrop, andlevelLeftExtMm/levelRightExtMmdatum extensions.documents.elevationView: An interior or exterior elevation looking fromfrom..to(direction +1 left / -1 right, depth default 20 ft); its live elevation marker (circle + pointer arrow with auto-updating detail#/sheet# head) prints automatically on overlapping plans.documents.enlargedPlan: A Revit-style enlarged plan in one step: creates a cropped plan view on the same level at enlarged scale (default 1/4" or 1/2" = 1'-0") AND places a live parametric callout bubble on the parent plan whose detail#/sheet# head auto-updates when the enlarged plan moves sheets.documents.callout: Places a live parametric callout box + split head bubble on a view referencing any existing enlarged plan, 2D detail, section, or elevation view.documents.setCrop: Sets a view's crop box in typed units, toggles cropView/showCropBox, or adjusts section/elevation far clip depth, level datum extensions (levelLeftExtMm/levelRightExtMm), and section markheadExt/tailExt/splitGap.documents.duplicateView: A copy of a view (another discipline's plan of the same level); returns the new id.documents.place: Puts a view (a plan, a schedule, a detail) on a sheet at a point (its centre, from the sheet's lower-left corner), with optional scale and viewport title offset/rule length; returns the viewport's id.documents.setViewportTitle: Moves a placed viewport's title block on its sheet (offset) and/or changes the horizontal title underline length (ruleLength, ornullto reset).documents.editSchedule: Edits a list schedule view in one undo step: add, move, remove or rename columns, filter, sort, group, totals (an equipment schedule's sort, a fixture schedule's DFU total).documents.schedule: A schedule view; returns its id.documents.tag: A tag on one element in a plan view (its mark, size or the right text for its kind), with a leader; returns the tag's id.documents.moveTag: Moves an existing tag in a plan view to a clear position (and optionally toggles its leader).documents.planLabels: Returns every rendered text label on a plan view (paper mm coordinates and bounding boxes) plus any overlapping pairs, so scripts can verify legibility and move colliding tags.documents.dimension: A dimension between two points in a view, tied to elements with refs so it follows them; returns its id.documents.tagStyle: A new tag style: field lines, box, orientation, what it applies to, and an arrow along the run (arrow: "down_slope"points downhill on the view's paper,"up_slope"uphill; level pipe shows none); returns its id.documents.setTagStyle: Changes a tag style's look: lines, box, orientation, applies-to, mask, textStyleId or its arrow (arrow: "none"removes it).documents.textStyle: Creates a model-wide Text Type (font family, paper cap height, bold/italic/uppercase, opaque or transparent background mask, default drawing roles) so part marks, circuit labels, tags, dimensions and room labels stay unified and readable over crossing lines.documents.setTextStyle: Updates an existing model-wide Text Type (size, font family, bold/italic/uppercase, opaque background mask, color, or default drawing roles).documents.deleteTextStyle: Deletes a model-wide Text Type by id.documents.flipWireArc: Flips (or explicitly sets) which side an automatic circuit or switch-leg arc bows toward on a plan view.documents.setCircuitGraphics: Sets a plan view's circuit and switch-leg drawing style (showCircuits: falsemakes a dedicated controls schematic plan), home runs, switch-leg letters, and ANSI/NECA 100 wire hash marks (home_runs,home_runs_and_switch_legs, orall_runs) while keeping existing wire waypoints and home-run offsets intact.documents.setSwitchLegLabelOffset: Repositions (or resets withnull) one lowercase switch-leg letter ("a","b") relative to its device anchor on a plan view.documents.setMwbcGroup: Groups (or splits withnull) branch circuits on the same panel into a shared-neutral Multi-Wire Branch Circuit (MWBC, NEC 210.4) drawn as one multi-arrowhead combined home run with shared neutral hash marks.documents.setWirePath: Pins one or more spline/orthogonal control vertices on a circuit or switch-leg wire span (hintKeyis the link id or"switch:<leg>"). 1 point draws a smooth arc, 2+ points draw a Catmull-Rom spline, andnullresets to automatic routing.documents.setHomeRun: Aims, resizes, curves, re-attaches, or moves the label of a circuit's home run arrow using offsets relative to its host device so the home run still follows when the device moves.documents.keynote: Gives elements a keynote by its key ("P1", "M3"); a keynote tag on a view prints the key and the sheet's keynote list (Sheets › Live table › Keynote list) gives its words from the keynote tables in force.documents.scheduleRows: A schedule's rows as numbers and words, on the model as the script has it so far: cells by column id (quantities in SI), grand totals, the row count.documents.scheduleFields: What a schedule can list and show: every class (no argument), or each named class's fields (path, label, type, unit, how it totals) and relationships for aggregate columns.documents.autoTag: Tag every untagged element ofcategories(duct,pipe,air_terminal,equipment,fixture,part,room,space,opening) in a view as movableDrawingItemtags placed clear of linework and other tags.documents.autoDimension: Dimensions runs, walls or grid lines in a plan or section as one edit: each (one dimension along every element) or chain (one string across them).documents.packSheet: Arranges a sheet's viewports in its drawing area (the editor's Arrange): packed or a grid, optionally shrinking views to a standard scale that fits, as one edit.documents.diagramKinds: Lists every live diagram kind registered by active packs ("one_line","electrical_riser","controls_diagram","plumbing_riser", …) with its label.documents.diagram: Creates a live diagram view derived from the model by any active pack ("one_line","electrical_riser","controls_diagram","plumbing_riser", …;documents.diagramKinds(ctx)lists all available kinds).documents.oneLine: A one-line, riser, or pack-contributed live diagram in a new drafting view: drawn from a distribution you describe (diagram), or live from the model (live: "one_line", "electrical_riser", "controls_diagram", "plumbing_riser"…).documents.detailLibrary: The 2D detail library: components (id, name, category, default size in mm, whether it stretches), hatch and line patterns, line styles and weights.documents.formKinds: The form schedule kinds the model's add-ons offer (panel, switchboard, feeder, connection_types, equipment_connections, lighting_controls…) and whether each is the schedule of one element.documents.formSchedule: A form schedule view (panel, switchboard, feeder, lighting_controls…) with the add-on's built-in form, filled live from the model; rules (a load read's rules.id) prints code demand factors.
documents.sheet
A new sheet (number, name, title block); returns its id.
sheet(ctx: ScriptContext, spec: { number: string; name: string; titleBlock?: TitleBlock; fields?: Record<string, string>; id?: string }): stringTopics: sheet, drawing, title block, sheets
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
documents.sheet(ctx, { number: "M-101", name: "Mechanical plan, Level 1" });
},
});documents.setSheet
Changes a sheet's number, name, title block or fields.
setSheet(ctx: ScriptContext, sheetId: string, changes: { number: string; name: string; titleBlock?: TitleBlock; fields?: Record<string, string> }): voidTopics: sheet, rename, title block fields
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const s = documents.sheet(ctx, { number: "M-101", name: "Mechanical plan" });
documents.setSheet(ctx, s, { number: "M-101", name: "Mechanical plan, Level 1", fields: { drawn_by: "KE" } });
},
});documents.planView
A floor plan of one level (for a discipline, scale, detailLevel, symbolScale, showLineCodes, and per-category/service overrides including singleLineBelow); returns the view's id.
planView(ctx: ScriptContext, spec: PlanViewSpec): stringTopics: view, plan, floor plan, detail level, symbolScale, annotative, single line, double line, line code
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
documents.planView(ctx, { level: "L1", name: "Level 1 - Plumbing", discipline: "plumbing", scale: 48, detailLevel: "medium" });
},
});documents.setView
Changes a view's detail level (coarse/medium/fine), visual style, annotative symbolScale (0.5–3.0), inline service codes, scale, discipline, or per-category/service graphics overrides (including singleLineBelow).
setView(ctx: ScriptContext, viewId: string, changes: ViewChanges): voidTopics: view, detail level, symbolScale, annotative, category overrides, single line, double line, schematic, line code
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plumbing", discipline: "plumbing" });
documents.setView(ctx, plan, { detailLevel: "medium", showLineCodes: true, scale: 48 });
},
});documents.ceilingView
A reflected ceiling plan of one level; returns the view's id.
ceilingView(ctx: ScriptContext, spec: PlanViewSpec): stringTopics: view, ceiling, rcp
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
documents.ceilingView(ctx, { level: "L1", name: "Level 1 - RCP", scale: 48 });
},
});documents.sectionView
A vertical building section cut from from to to (direction +1 left / -1 right, depth default 20 ft); supports annotative headExt/tailExt, Revit splitGap break, explicit crop, and levelLeftExtMm/levelRightExtMm datum extensions. Its live section mark prints automatically on overlapping plans. Returns the view's id.
sectionView(ctx: ScriptContext, spec: VerticalViewSpec): stringTopics: view, section, section cut, building section, section marker, split gap, level lines
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const sec = documents.sectionView(ctx, { name: "Building Section A-A", from: { x: units.ft(0), y: units.ft(10) }, to: { x: units.ft(30), y: units.ft(10) }, direction: 1, depth: units.ft(15), scale: 48, splitGap: true });
const sheet = documents.sheet(ctx, { number: "A-301", name: "Sections" });
documents.place(ctx, sheet, sec, { x: units.mm(400), y: units.mm(300) });
},
});documents.elevationView
An interior or exterior elevation looking from from..to (direction +1 left / -1 right, depth default 20 ft); its live elevation marker (circle + pointer arrow with auto-updating detail#/sheet# head) prints automatically on overlapping plans. Returns the view's id.
elevationView(ctx: ScriptContext, spec: VerticalViewSpec): stringTopics: view, elevation, interior elevation, exterior elevation, elevation marker
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const elev = documents.elevationView(ctx, { name: "Restroom North Elevation", from: { x: units.ft(2), y: units.ft(8) }, to: { x: units.ft(12), y: units.ft(8) }, direction: 1, depth: units.ft(10), scale: 24 });
const sheet = documents.sheet(ctx, { number: "A-401", name: "Interior Elevations" });
documents.place(ctx, sheet, elev, { x: units.mm(400), y: units.mm(300) });
},
});documents.enlargedPlan
A Revit-style enlarged plan in one step: creates a cropped plan view on the same level at enlarged scale (default 1/4" or 1/2" = 1'-0") AND places a live parametric callout bubble on the parent plan whose detail#/sheet# head auto-updates when the enlarged plan moves sheets. Returns { viewId, calloutId }.
enlargedPlan(ctx: ScriptContext, spec: EnlargedPlanSpec): { viewId: string; calloutId: string }Topics: view, enlarged plan, callout, callout bubble, plan callout, detail callout
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
const { viewId } = documents.enlargedPlan(ctx, { parent: plan, name: "Enlarged Restroom Plan", from: { x: units.ft(0), y: units.ft(0) }, to: { x: units.ft(12), y: units.ft(10) }, scale: 24 });
const sheet = documents.sheet(ctx, { number: "P-401", name: "Enlarged Plumbing Plans" });
documents.place(ctx, sheet, viewId, { x: units.mm(300), y: units.mm(300) });
},
});documents.callout
Places a live parametric callout box + split head bubble on a view referencing any existing enlarged plan, 2D detail, section, or elevation view. The head reads the target's live detail#/sheet# automatically; returns the callout's id.
callout(ctx: ScriptContext, spec: CalloutRefSpec): stringTopics: callout, callout bubble, view reference, enlarged plan, detail reference
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
const detail = documents.planView(ctx, { level: "L1", name: "Enlarged Core", scale: 24, crop: { from: { x: units.ft(0), y: units.ft(0) }, to: { x: units.ft(10), y: units.ft(10) } } });
documents.callout(ctx, { view: plan, target: detail, from: { x: units.ft(0), y: units.ft(0) }, to: { x: units.ft(10), y: units.ft(10) }, label: "EEP" });
},
});documents.setCrop
Sets a view's crop box in typed units, toggles cropView/showCropBox, or adjusts section/elevation far clip depth, level datum extensions (levelLeftExtMm/levelRightExtMm), and section mark headExt/tailExt/splitGap.
setCrop(ctx: ScriptContext, view: string, spec: CropBoxSpec): voidTopics: crop, crop box, view crop, enlarged plan, far clip, section marker, level lines
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
documents.setCrop(ctx, plan, { from: { x: units.ft(0), y: units.ft(0) }, to: { x: units.ft(15), y: units.ft(12) } });
},
});documents.duplicateView
A copy of a view (another discipline's plan of the same level); returns the new id.
duplicateView(ctx: ScriptContext, viewId: string, name: string, id?: string): stringTopics: view, copy, duplicate
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const m = documents.planView(ctx, { level: "L1", name: "Level 1 - Mechanical", discipline: "mechanical" });
documents.duplicateView(ctx, m, "Level 1 - Plumbing");
},
});documents.place
Puts a view (a plan, a schedule, a detail) on a sheet at a point (its centre, from the sheet's lower-left corner), with optional scale and viewport title offset/rule length; returns the viewport's id.
place(ctx: ScriptContext, sheetId: string, viewId: string, at: SheetPoint, scale?: number, title?: { offset?: { x: Measure; y: Measure }; ruleLength?: Measure }): stringTopics: viewport, place, sheet, layout, view title
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const s = documents.sheet(ctx, { number: "M-101", name: "Mechanical plan" });
const v = documents.planView(ctx, { level: "L1", name: "L1 Mechanical" });
documents.place(ctx, s, v, { x: units.mm(420), y: units.mm(300) });
},
});documents.setViewportTitle
Moves a placed viewport's title block on its sheet (offset) and/or changes the horizontal title underline length (ruleLength, or null to reset).
setViewportTitle(ctx: ScriptContext, viewportId: string, spec: { offset?: { x: Measure; y: Measure }; ruleLength?: Measure | null }): voidTopics: viewport, view title, title line, sheet, layout
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const s = documents.sheet(ctx, { number: "A-101", name: "Floor Plan" });
const v = documents.planView(ctx, { level: "L1", name: "L1 Plan" });
const vp = documents.place(ctx, s, v, { x: units.mm(420), y: units.mm(300) });
documents.setViewportTitle(ctx, vp, { offset: { x: units.mm(0), y: units.mm(12) }, ruleLength: units.mm(95) });
},
});documents.editSchedule
Edits a list schedule view in one undo step: add, move, remove or rename columns, filter, sort, group, totals (an equipment schedule's sort, a fixture schedule's DFU total). The same steps the grid's Columns menu and the agent's bim_schedule_define send; a form schedule (panel slots) refuses.
editSchedule(ctx: ScriptContext, viewId: string, steps: ScheduleEditStep[]): voidTopics: schedule, columns, rename column, sort, filter, group, totals
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { ids: ["sched-equipment"] },
parameters: {},
run(ctx) {
documents.editSchedule(ctx, "sched-equipment", [{ op: "rename_column", columnId: "mark", heading: "TAG" }, { op: "sort", sort: [{ path: "mark", direction: "asc" }] }, { op: "totals", show: true }]);
},
});documents.schedule
A schedule view; returns its id. Give classes (rooms, spaces, zones, equipment, any class documents.scheduleFields lists) with field paths or full columns, filters, sort, groups and totals; or a category for a one-category list. Put it on a sheet with documents.place; change it later with documents.editSchedule.
schedule(ctx: ScriptContext, spec: { name: string; category: ScheduleCategory; columns: readonly string[]; title?: string; id?: string } | { name: string; classes: readonly string[]; columns: readonly (string | ScheduleColumn)[]; levels?: readonly string[]; filters?: readonly ScheduleFilter[]; sort?: readonly (string | { path: string; direction: "asc" | "desc" })[]; groups?: readonly (string | { path: string; header?: boolean; footer?: boolean; totals?: boolean })[]; totals?: boolean; includeSubclasses?: boolean; id?: string }): stringTopics: schedule, make a schedule, room schedule, space schedule, equipment schedule, table, classes
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(32), y: units.ft(0) }, { x: units.ft(32), y: units.ft(14) }, { x: units.ft(0), y: units.ft(14) }], closed: true, thickness: units.in(6), height: units.ft(9) });
building.walls(ctx, { level: "L1", points: [{ x: units.ft(14), y: units.ft(0) }, { x: units.ft(14), y: units.ft(14) }], thickness: units.in(4), height: units.ft(9) });
const bedroom = building.room(ctx, { level: "L1", number: "101", name: "Bedroom", outline: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(14), y: units.ft(0) }, { x: units.ft(14), y: units.ft(14) }, { x: units.ft(0), y: units.ft(14) }] });
const living = building.room(ctx, { level: "L1", number: "102", name: "Living room", outline: [{ x: units.ft(14), y: units.ft(0) }, { x: units.ft(32), y: units.ft(0) }, { x: units.ft(32), y: units.ft(14) }, { x: units.ft(14), y: units.ft(14) }] });
const rooms = documents.schedule(ctx, { name: "Room schedule", classes: ["arch.room"], columns: ["number", "name", "area"], sort: ["number"], totals: true });
const equipmentSchedule = documents.schedule(ctx, { name: "Equipment schedule", category: "mechanical_equipment", columns: ["mark", "type_name", "level"] });
const sheet = documents.sheet(ctx, { number: "A-601", name: "Schedules" });
documents.place(ctx, sheet, rooms, { x: units.mm(150), y: units.mm(400) });
documents.place(ctx, sheet, equipmentSchedule, { x: units.mm(450), y: units.mm(400) });
},
});documents.tag
A tag on one element in a plan view (its mark, size or the right text for its kind), with a leader; returns the tag's id.
tag(ctx: ScriptContext, spec: { view: string; element: string; at: { x: Measure; y: Measure }; template?: TagTemplate; fields?: readonly string[]; leader?: boolean; leaderOverride?: boolean; elbow?: "auto" | { x: Measure; y: Measure }; mask?: boolean; textSizeMm?: number; styleId?: string; id?: string }): stringTopics: tag, tags, label, mark, annotate
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
documents.tag(ctx, { view: plan, element: walls.element(1), at: { x: units.ft(10), y: units.ft(-3) } });
},
});documents.moveTag
Moves an existing tag in a plan view to a clear position (and optionally toggles its leader).
moveTag(ctx: ScriptContext, tagId: string, at: { x: Measure; y: Measure }, opts?: { leader?: boolean }): voidTopics: move tag, tag, label, overlap, legibility
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
const t = documents.tag(ctx, { view: plan, element: walls.element(1), at: { x: units.ft(10), y: units.ft(-3) } });
documents.moveTag(ctx, t, { x: units.ft(12), y: units.ft(-4) }, { leader: true });
},
});documents.planLabels
Returns every rendered text label on a plan view (paper mm coordinates and bounding boxes) plus any overlapping pairs, so scripts can verify legibility and move colliding tags.
planLabels(ctx: ScriptContext, viewRef: string): { viewId: string; scale: number; labels: { text: string; at: { xMm: number; yMm: number }; sizeMm: number; anchor: string; box: { minX: number; minY: number; maxX: number; maxY: number } }[]; overlaps: { a: string; b: string; overlapAreaMm2: number }[] }Topics: plan labels, overlaps, legibility, tags, inspect, qa
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
const report = documents.planLabels(ctx, plan);
ctx.label(`${report.labels.length} labels, ${report.overlaps.length} overlaps`);
},
});documents.dimension
A dimension between two points in a view, tied to elements with refs so it follows them; returns its id.
dimension(ctx: ScriptContext, spec: { view: string; from: PlanPoint; to: PlanPoint; refs?: ({ elementId: string; anchor: string } | null)[]; offset?: Measure; kind?: "linear" | "aligned"; id?: string }): stringTopics: dimension, dimensions, measure, annotate
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
documents.dimension(ctx, { view: plan, from: { x: units.ft(0), y: units.ft(0) }, to: { x: units.ft(30), y: units.ft(0) }, refs: [{ elementId: walls.element(1), anchor: "start" }, { elementId: walls.element(1), anchor: "end" }] });
},
});documents.tagStyle
A new tag style: field lines, box, orientation, what it applies to, and an arrow along the run (arrow: "down_slope" points downhill on the view's paper, "up_slope" uphill; level pipe shows none); returns its id.
tagStyle(ctx: ScriptContext, spec: Omit<Extract<EditCommand, { type: "create_tag_style" }>, "type" | "styleId"> & { id?: string }): stringTopics: tag style, slope arrow, downhill arrow, drain slope tag, tag, arrow
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: {},
parameters: {},
run(ctx) {
documents.tagStyle(ctx, { name: "Drain slope", lines: ["[{pipe.slope}]"], box: "none", orientation: "along", appliesTo: ["pipe"], arrow: "down_slope" });
},
});documents.setTagStyle
Changes a tag style's look: lines, box, orientation, applies-to, mask, textStyleId or its arrow (arrow: "none" removes it).
setTagStyle(ctx: ScriptContext, styleId: string, changes: Omit<Extract<EditCommand, { type: "update_tag_style" }>, "type" | "styleId">): voidTopics: tag style, slope arrow, edit tag style
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: {},
parameters: {},
run(ctx) {
const style = documents.tagStyle(ctx, { name: "Drain size and slope", lines: ["{pipe.size}[ @ {pipe.slope}]"], appliesTo: ["pipe"] });
documents.setTagStyle(ctx, style, { arrow: "down_slope" });
},
});documents.textStyle
Creates a model-wide Text Type (font family, paper cap height, bold/italic/uppercase, opaque or transparent background mask, default drawing roles) so part marks, circuit labels, tags, dimensions and room labels stay unified and readable over crossing lines.
textStyle(ctx: ScriptContext, spec: { name: string; textSizeMm?: number; fontFamily?: string; bold?: boolean; italic?: boolean; uppercase?: boolean; background?: "opaque" | "transparent"; color?: string; defaultFor?: readonly TextStyleRole[]; id?: string }): stringTopics: text type, text style, font, opaque background, text mask, wipeout, typography
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: {},
parameters: {},
run(ctx) {
const ts = documents.textStyle(ctx, { name: "3/32\" Crisp Opaque", textSizeMm: 2.4, background: "opaque", defaultFor: ["part_mark", "link_label", "tag"] });
documents.setTextStyle(ctx, ts, { bold: true });
},
});documents.setTextStyle
Updates an existing model-wide Text Type (size, font family, bold/italic/uppercase, opaque background mask, color, or default drawing roles).
setTextStyle(ctx: ScriptContext, styleId: string, changes: { name?: string; textSizeMm?: number; fontFamily?: string | null; bold?: boolean; italic?: boolean; uppercase?: boolean; background?: "opaque" | "transparent"; color?: string | null; defaultFor?: readonly TextStyleRole[] }): voidTopics: text type, text style, edit text style, font, opaque background
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: {},
parameters: {},
run(ctx) {
const ts = documents.textStyle(ctx, { name: "Notes", textSizeMm: 2.4 });
documents.setTextStyle(ctx, ts, { bold: true, background: "opaque" });
},
});documents.deleteTextStyle
Deletes a model-wide Text Type by id.
deleteTextStyle(ctx: ScriptContext, styleId: string): voidTopics: text type, text style, delete text style
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: {},
parameters: {},
run(ctx) {
const ts = documents.textStyle(ctx, { name: "Temp", textSizeMm: 2.4 });
documents.deleteTextStyle(ctx, ts);
},
});documents.flipWireArc
Flips (or explicitly sets) which side an automatic circuit or switch-leg arc bows toward on a plan view.
flipWireArc(ctx: ScriptContext, viewRef: string, hintKey: string, fromElementId: string, toElementId: string, flipped?: boolean): voidTopics: wire arc, flip wire, circuit graphics, arc side
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
documents.flipWireArc(ctx, plan, "ckt-1", "r-1", "r-2", true);
},
});documents.setCircuitGraphics
Sets a plan view's circuit and switch-leg drawing style (showCircuits: false makes a dedicated controls schematic plan), home runs, switch-leg letters, and ANSI/NECA 100 wire hash marks (home_runs, home_runs_and_switch_legs, or all_runs) while keeping existing wire waypoints and home-run offsets intact.
setCircuitGraphics(ctx: ScriptContext, viewRef: string, settings: CircuitGraphicsSettingsSpec): voidTopics: circuit graphics, wire style, hash marks, tick marks, switch legs, home runs, controls plan
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
documents.setCircuitGraphics(ctx, plan, { style: "arcs", showCircuits: true, homeRuns: true, switchLegs: true, switchLegLabels: true, hashMarks: "hots_neutral_ground", hashMarksOn: "home_runs_and_switch_legs" });
},
});documents.setSwitchLegLabelOffset
Repositions (or resets with null) one lowercase switch-leg letter ("a", "b") relative to its device anchor on a plan view.
setSwitchLegLabelOffset(ctx: ScriptContext, viewRef: string, hintKey: string, memberId: string, offset: { x: Measure; y: Measure } | null): voidTopics: switch leg label, move switch letter, control designation
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
documents.setSwitchLegLabelOffset(ctx, plan, "switch:a", "sw-1", { x: units.in(14), y: units.in(8) });
},
});documents.setMwbcGroup
Groups (or splits with null) branch circuits on the same panel into a shared-neutral Multi-Wire Branch Circuit (MWBC, NEC 210.4) drawn as one multi-arrowhead combined home run with shared neutral hash marks.
setMwbcGroup(ctx: ScriptContext, viewRef: string, linkIds: readonly string[], groupName: string | null): voidTopics: mwbc, multi-wire branch circuit, shared neutral, combined home run, double arrowhead
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
documents.setMwbcGroup(ctx, plan, ["ckt-1", "ckt-3"], "mwbc-1");
},
});documents.setWirePath
Pins one or more spline/orthogonal control vertices on a circuit or switch-leg wire span (hintKey is the link id or "switch:<leg>"). 1 point draws a smooth arc, 2+ points draw a Catmull-Rom spline, and null resets to automatic routing.
setWirePath(ctx: ScriptContext, viewRef: string, hintKey: string, fromElementId: string, toElementId: string, waypoints: readonly PlanPoint[] | null): voidTopics: spline wire, wire vertices, wire path, bend circuit, arc wire
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
documents.setWirePath(ctx, plan, "ckt-1", "r-1", "r-2", [{ x: units.ft(10), y: units.ft(12) }, { x: units.ft(16), y: units.ft(13) }]);
},
});documents.setHomeRun
Aims, resizes, curves, re-attaches, or moves the label of a circuit's home run arrow using offsets relative to its host device so the home run still follows when the device moves. Pass null to reset.
setHomeRun(ctx: ScriptContext, viewRef: string, linkId: string, spec: HomeRunSpec | null): voidTopics: home run, move home run, home run arrow, circuit label, home run curve
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
documents.setHomeRun(ctx, plan, "ckt-1", { tipOffset: { x: units.ft(-4), y: units.ft(-1.5) }, bendOffset: { x: units.ft(-2), y: units.ft(-2) } });
},
});documents.keynote
Gives elements a keynote by its key ("P1", "M3"); a keynote tag on a view prints the key and the sheet's keynote list (Sheets › Live table › Keynote list) gives its words from the keynote tables in force.
keynote(ctx: ScriptContext, elementIds: readonly string[], key: string): voidTopics: keynote, key note, general note, legend, note number
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { ids: ["duct-1", "duct-2"] },
parameters: {},
run(ctx) {
documents.keynote(ctx, ["duct-1", "duct-2"], "M1");
},
});documents.scheduleRows
A schedule's rows as numbers and words, on the model as the script has it so far: cells by column id (quantities in SI), grand totals, the row count. Form schedules (panels, feeders) are add-on reads (electrical.loads).
scheduleRows(ctx: ScriptContext, schedule: string, window?: { offset?: number; limit?: number }): ScheduleRowsTopics: schedule rows, read a schedule, totals, room areas, schedule values
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(32), y: units.ft(0) }, { x: units.ft(32), y: units.ft(14) }, { x: units.ft(0), y: units.ft(14) }], closed: true, thickness: units.in(6), height: units.ft(9) });
building.walls(ctx, { level: "L1", points: [{ x: units.ft(14), y: units.ft(0) }, { x: units.ft(14), y: units.ft(14) }], thickness: units.in(4), height: units.ft(9) });
const bedroom = building.room(ctx, { level: "L1", number: "101", name: "Bedroom", outline: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(14), y: units.ft(0) }, { x: units.ft(14), y: units.ft(14) }, { x: units.ft(0), y: units.ft(14) }] });
const living = building.room(ctx, { level: "L1", number: "102", name: "Living room", outline: [{ x: units.ft(14), y: units.ft(0) }, { x: units.ft(32), y: units.ft(0) }, { x: units.ft(32), y: units.ft(14) }, { x: units.ft(14), y: units.ft(14) }] });
const rooms = documents.schedule(ctx, { name: "Room schedule", classes: ["arch.room"], columns: ["number", "name", "area"], sort: ["number"], totals: true });
const read = documents.scheduleRows(ctx, rooms);
const m2 = read.rows.reduce((sum, r) => sum + Number(r.cells.area ?? 0), 0);
ctx.label(`${read.totalRows} rooms, ${Math.round(m2 * 10.7639)} sq ft`);
},
});documents.scheduleFields
What a schedule can list and show: every class (no argument), or each named class's fields (path, label, type, unit, how it totals) and relationships for aggregate columns.
scheduleFields(ctx: ScriptContext, classes?: readonly string[]): readonly ScheduleClassFields[]Topics: schedule fields, schedule classes, what can a schedule show, columns
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const space = documents.scheduleFields(ctx, ["gen.space"])[0];
const fields = (space?.fields ?? []).filter((f) => f.path === "area" || f.path === "occupants").map((f) => f.path);
documents.schedule(ctx, { name: "Space schedule", classes: ["gen.space"], columns: ["number", "name", ...fields], totals: true });
},
});documents.autoTag
Tag every untagged element of categories (duct, pipe, air_terminal, equipment, fixture, part, room, space, opening) in a view as movable DrawingItem tags placed clear of linework and other tags.
autoTag(ctx: ScriptContext, spec: { view: string; categories: readonly AutoTagCategory[]; leaders?: "always" | "never" | "when_away"; includeTagged?: boolean; only?: readonly string[]; textHeight?: Measure; styleId?: string }): { tagged: number; skipped: readonly { elementId: string; reason: string }[] }Topics: auto tag, tag all, tag every duct, tags, annotate
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "route",
reads: { levels: true },
parameters: {},
run(ctx) {
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Mechanical", scale: 48, cutHeight: units.ft(10) });
routes.along(ctx, { level: "L1", domain: "duct", size: routes.rect(units.in(20), units.in(12)), system: { id: "sa-1", kind: "supply_air" }, height: units.ft(9), points: [{ x: units.ft(2), y: units.ft(10) }, { x: units.ft(28), y: units.ft(10) }] });
routes.along(ctx, { level: "L1", domain: "duct", size: routes.rect(units.in(20), units.in(12)), system: { id: "ra-1", kind: "return_air" }, height: units.ft(9), points: [{ x: units.ft(15), y: units.ft(2) }, { x: units.ft(15), y: units.ft(18) }] });
const done = documents.autoTag(ctx, { view: plan, categories: ["duct"] });
ctx.label(`${done.tagged} duct tags`);
},
});documents.autoDimension
Dimensions runs, walls or grid lines in a plan or section as one edit: each (one dimension along every element) or chain (one string across them). Every dimension follows its elements.
autoDimension(ctx: ScriptContext, spec: { view: string; elements: readonly string[]; mode: "each" | "chain"; direction?: "horizontal" | "vertical"; offset?: Measure }): voidTopics: auto dimension, dimension walls, dimension string, chain dimension, dimensions
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
documents.autoDimension(ctx, { view: plan, elements: [walls.element(1), walls.element(2)], mode: "each" });
},
});documents.packSheet
Arranges a sheet's viewports in its drawing area (the editor's Arrange): packed or a grid, optionally shrinking views to a standard scale that fits, as one edit. Returns how many moved.
packSheet(ctx: ScriptContext, sheet: string, spec?: { mode?: "pack" | "grid"; columns?: number; fitScales?: boolean; minScale?: number; order?: readonly string[]; gap?: Measure }): { moved: number }Topics: sheet layout, arrange sheet, pack views, sheet packing, fit views
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const sheet = documents.sheet(ctx, { number: "M-101", name: "Plans" });
for (const level of ctx.model.levels()) {
const view = documents.planView(ctx, { level: level.id, name: `${String(level.name)} - Mechanical`, scale: 48 });
documents.place(ctx, sheet, view, { x: units.mm(100), y: units.mm(100) });
}
documents.packSheet(ctx, sheet, { fitScales: true });
},
});documents.diagramKinds
Lists every live diagram kind registered by active packs ("one_line", "electrical_riser", "controls_diagram", "plumbing_riser", …) with its label.
diagramKinds(ctx: ScriptContext): readonly { kind: string; label: string }[]Topics: diagram kinds, controls diagram, one-line, riser diagram, live diagram
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
ctx.label(documents.diagramKinds(ctx).map((d) => d.kind).join(", "));
ctx.edit({ type: "create_level", levelId: ctx.id("level"), name: "Roof", elevationMm: 9000 });
},
});documents.diagram
Creates a live diagram view derived from the model by any active pack ("one_line", "electrical_riser", "controls_diagram", "plumbing_riser", …; documents.diagramKinds(ctx) lists all available kinds). Returns the view's id.
diagram(ctx: ScriptContext, spec: { name: string; kind: string; hints?: DiagramHints; id?: string }): stringTopics: diagram, live diagram, controls diagram, lighting controls diagram, one-line, riser
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const ctrl = documents.diagram(ctx, { name: "E-501 Lighting Controls Diagram", kind: "controls_diagram" });
const sheet = documents.sheet(ctx, { number: "E-501", name: "Electrical Diagrams" });
documents.place(ctx, sheet, ctrl, { x: units.mm(300), y: units.mm(300) }, 1);
},
});documents.oneLine
A one-line, riser, or pack-contributed live diagram in a new drafting view: drawn from a distribution you describe (diagram), or live from the model (live: "one_line", "electrical_riser", "controls_diagram", "plumbing_riser"…). Returns the view's id.
oneLine(ctx: ScriptContext, spec: { name: string; diagram: { title?: string; roots: readonly OneLineNode[]; notes?: readonly string[] }; id?: string } | { name: string; live: string; hints?: Record<string, unknown>; id?: string }): stringTopics: one-line, single line, riser diagram, electrical diagram, distribution diagram, controls diagram
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const diagram = documents.oneLine(ctx, { name: "E-601 One-line", diagram: { roots: [{ id: "utility", kind: "utility", name: "Utility", children: [{ id: "msb", kind: "switchboard", name: "MSB", ratings: ["800A", "208Y/120V"], children: [{ id: "lp1", kind: "panelboard", name: "LP-1" }] }] }] } });
const sheet = documents.sheet(ctx, { number: "E-601", name: "One-line diagram" });
documents.place(ctx, sheet, diagram, { x: units.mm(300), y: units.mm(300) }, 1);
},
});documents.detailLibrary
The 2D detail library: components (id, name, category, default size in mm, whether it stretches), hatch and line patterns, line styles and weights. Use a component id as the symbol of a detail item.
detailLibrary(ctx: ScriptContext): { components: readonly { id: string; name: string; category: string; widthMm: number; heightMm: number; linear: boolean }[]; hatchPatterns: readonly string[]; linePatterns: readonly string[]; lineStyles: readonly { id: string; name: string }[]; lineWeights: readonly string[] }Topics: detail components, detail library, hatch patterns, line styles, symbols
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
const library = documents.detailLibrary(ctx);
ctx.label(`${library.components.length} detail components`);
ctx.edit({ type: "create_level", levelId: ctx.id("level"), name: "Roof", elevationMm: 9000 });
},
});documents.formKinds
The form schedule kinds the model's add-ons offer (panel, switchboard, feeder, connection_types, equipment_connections, lighting_controls…) and whether each is the schedule of one element.
formKinds(ctx: ScriptContext): readonly { kind: string; boundToElement: boolean }[]Topics: form schedule, panel schedule, switchboard schedule, feeder schedule, lighting controls schedule
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
ctx.label(documents.formKinds(ctx).map((f) => f.kind).join(", "));
ctx.edit({ type: "create_level", levelId: ctx.id("level"), name: "Roof", elevationMm: 9000 });
},
});documents.formSchedule
A form schedule view (panel, switchboard, feeder, lighting_controls…) with the add-on's built-in form, filled live from the model; rules (a load read's rules.id) prints code demand factors. Returns its id; put it on a sheet with documents.place.
formSchedule(ctx: ScriptContext, spec: { kind: string; name: string; element?: string; rules?: string; id?: string }): stringTopics: panel schedule, form schedule, switchboard schedule, lighting controls schedule, controls schedule, schedule a panel
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true, kinds: ["part"] },
parameters: {},
run(ctx) {
equipment.place(ctx, { level: "L1", type: "builtin:panelboard-125-208-1ph@1", at: { x: units.ft(1), y: units.ft(13) }, mark: "LP-1" });
const panel = ctx.model.ofKind("part").find((p) => p.mark === "LP-1");
if (!panel) throw new Error("No LP-1");
const loads = ctx.read<{ rules: { id: string } }>("electrical.loads", { panel: "LP-1", nec_edition: "2023" });
const schedule = documents.formSchedule(ctx, { kind: "panel", name: "Panel LP-1 schedule", element: panel.id, rules: loads.rules.id });
const controls = documents.formSchedule(ctx, { kind: "lighting_controls", name: "Lighting controls schedule" });
const sheet = documents.sheet(ctx, { number: "E-601", name: "Panel & control schedules" });
documents.place(ctx, sheet, schedule, { x: units.mm(250), y: units.mm(350) });
documents.place(ctx, sheet, controls, { x: units.mm(620), y: units.mm(350) });
},
});