Areas

The FAR / built-up-area rollup for the active program. Accessed via snaptrude.program.areas.

This is the zoning-compliance lens on the model: carpet / built-up / excluded area totals, the site area, and the achieved-vs-target FAR (Floor Area Ratio), plus groupings of those totals. It complements snaptrude.program.metrics (the department-allocation lens).

achievedFar is derived and read-only — computed from built-up area and site area. targetFar is the goal you set (via update); the two are the same ratio, one measured and one intended. The surface speaks FAR only — there is no FSI alias. All area figures are already in the program's display unit (ft2/m2).

Reads never throw. The engine recomputes the breakdown live only while the Area sidebar is open, so a plugin running headless should call refresh() first to guarantee get/list/listMembers are fresh. update is a non-undoable settings write persisted with the project.

Design options: when a design option (proposal) is active, the FAR inputs (target FAR, site area override, deviation) are scoped to that option — each option keeps its own set, exactly like the product's Area settings dialog. update writes the active option's settings and the summary reads (get / refresh / update's returned summary) report that same scope. Without design options there is a single project-wide set.

At a glance

Method	What it does	Mutates?
get()	The whole-program area / FAR summary	—
list(groupBy, categoryId?)	Area totals grouped by storey, building, or tag	—
listMembers(groupBy, groupId, categoryId?)	The spaces behind one group's total	—
refresh()	Recompute the breakdown on demand, return summary	— (recompute)
update(options?)	Set FAR inputs — target FAR, site area, deviation	✓ (not undoable)

Types

PluginProgramAreaSummary

The whole-program area / FAR summary. All area figures are in areaUnit; ratios are unitless.

Property	Type	Description
count	number	Number of spaces in the program (a count, not an area)
hiddenCount	number	Number of those spaces currently hidden
carpet	number	Total carpet area in areaUnit
builtUp	number	Total built-up area in areaUnit
excluded	number	Total excluded area in areaUnit
farBuiltUp	number	Built-up area that counts toward FAR, in areaUnit
siteArea	number	Site/plot area in areaUnit
achievedFar	number | null	Derived FAR (farBuiltUp / siteArea); null when site area or target FAR is unset
targetFar	number	The target FAR goal (set via update)
deviation	number	Allowed FAR deviation, as a percentage
areaUnit	"ft2" | "m2"	The unit every area figure above is reported in

PluginProgramAreaGroup

One bucket of the area rollup. Area figures are in the program's area unit; targetArea is in targetUnit.

Property	Type	Description
groupId	string	Stable id of the group (e.g. storey id, department id)
name	string	Display name of the group
color	string	CSS hex color for the group (empty for facets that have no color, e.g. storeys/buildings)
carpet	number	Carpet area for this group
builtUp	number	Built-up area for this group
excluded	number	Excluded area for this group
count	number	Number of spaces in this group
targetArea	number	Target area for this group, in targetUnit (labels, departments, and tagCategories carry native targets; storeys/buildings have none, so 0)
targetUnit	"ft2" | "m2"	The unit targetArea is reported in

PluginProgramAreaMember

A single space within an area group. Area figures are in the program's area unit.

Property	Type	Description
id	ComponentHandle	Component.id of the space (never a mesh handle)
label	string	Display label of the space
areaClass	PluginAreaClass	Effective area class — "NET" (→ carpet), "GROSS" (→ builtUp), or "EXCLUDED" (→ excluded)
carpet	number	Carpet area of the space
builtUp	number	Built-up area of the space
excluded	number	Excluded area of the space
isVisible	boolean	Whether the space is currently visible

PluginProgramAreaGroupBy

The facet to group the area rollup by: "labels" | "storeys" | "buildings" | "departments" | "tagCategories".

Functions

get()

Get the program area summary — the whole-program totals plus achieved vs target FAR and the area unit they're reported in.

• Returns: PluginProgramAreaSummary — achievedFar is null when the site area or target FAR is not set.

const s = await snaptrude.program.areas.get();
console.log(s.builtUp, s.siteArea, s.achievedFar, s.targetFar, s.areaUnit);

---

list(groupBy, categoryId?)

List the program area rollup grouped by a facet — by label, storey, building, department, or tag category.

• Parameters:
  • groupBy: PluginProgramAreaGroupBy — the facet to group by
  • categoryId: string | undefined — the tag category to group by (required when groupBy is "tagCategories")
• Returns: { groups: PluginProgramAreaGroup[] } — empty when the program has no spaces.
• Throws: If groupBy is "tagCategories" and categoryId is omitted.

const { groups } = await snaptrude.program.areas.list("storeys");
for (const g of groups) console.log(g.name, g.builtUp, g.count);

---

listMembers(groupBy, groupId, categoryId?)

List the spaces that make up one area group, with their per-space area figures.

• Parameters:
  • groupBy: PluginProgramAreaGroupBy — the same facet used to produce the group
  • groupId: string — the id of the group to expand
  • categoryId: string | undefined — the tag category context (required when groupBy is "tagCategories")
• Returns: { members: PluginProgramAreaMember[] } — empty when the group is missing or empty.

const { members } = await snaptrude.program.areas.listMembers("storeys", "st_2");
for (const m of members) console.log(m.label, m.carpet);

---

refresh()

Force the area breakdown to recompute, then return the fresh summary. The engine recomputes carpet / built-up / FAR totals live only while the Area sidebar is open — a plugin running headless can otherwise read a stale (or never-computed) snapshot from get/list/listMembers. Calling refresh drives the same native recompute on demand, so those reads then reflect the current model. This is a read (no write gate): it recomputes derived totals, it does not change the model.

Cost: a full pass over every space, floor, and mass in the active structure. Not free on large models — call it once before a batch of reads, not per read.

• Returns: PluginProgramAreaSummary — the freshly-recomputed summary.

const s = await snaptrude.program.areas.refresh();
const { groups } = await snaptrude.program.areas.list("storeys"); // now fresh
console.log(s.builtUp, groups.length);

---

update(options?)

A sparse update of the program-level FAR inputs — target FAR, site area, and allowed deviation. This is a non-undoable settings write (persisted with the project); achievedFar recomputes from these. The geometry totals are untouched.

With an active design option the write lands in that option's settings (the only scope the engine reads while an option is active) — switching options switches the FAR inputs with them. Setting siteArea marks the site area as user-overridden for that scope (the auto-computed site area is used otherwise).

• Parameters:
  • options.targetFar: number | undefined — new target FAR (≥ 0)
  • options.siteArea: number | undefined — site-area override (> 0), in the program's area unit
  • options.deviation: number | undefined — allowed FAR deviation percentage (0–100)
• Returns: PluginProgramAreaSummary — the recomputed summary.
• Throws: If a value is out of range.

const s = await snaptrude.program.areas.update({ targetFar: 2.5 });
console.log(s.achievedFar, s.targetFar);

Errors

Failed calls reject with a typed PluginError — see Error Handling. Conditions specific to this namespace:

Code	Thrown by	When	details
VALIDATION	list, listMembers	groupBy is "tagCategories" but categoryId is omitted	issues

Reads are otherwise total: an unknown groupId in listMembers returns an empty members array, and get/list never throw for an empty program. update has no namespace-specific failure beyond argument validation (out-of-range values are VALIDATION).