Site

Read the planning context of the project's site/plot. Accessed via snaptrude.program.site.

The site is the set of plot/parcel footprints the program is planned against: their total area, per-parcel footprints (world XZ plan coordinates in Snaptrude units — the same plan space as a space's planPoints), and — when the project is geo-located on terrain — their geographic (latitude/longitude) rings. This is the program-planning view of the site; zoning numbers (setbacks, FAR/FSI, height limits) live in the site-analysis sheet and are not read here.

All methods are host API calls that return Promises. All are reads and never throw: get returns an empty snapshot (zero totals) when there is no site, the list methods return [], and getContext returns null.

At a glance

Method	What it does	Mutates?
get()	Snapshot of the site: total area, parcel count, per-parcel footprints	—
getArea()	Just the total site area and its units	—
listPolygons()	Each parcel's footprint in world XZ coordinates (Snaptrude units)	—
listGeoPolygons()	Each parcel as a ring of geographic latitude/longitude points	—
getContext()	Geo-referenced terrain context: map center, bounds, size, zoom, parcels	—
getLocation()	The project's geo-location as {latitude, longitude}	—
getNorthAngle()	True-north angle in degrees, from the terrain rotation	—

Geo-located projects only

listGeoPolygons, getContext, getLocation, and getNorthAngle return data only when the project is geo-located on terrain — otherwise listGeoPolygons returns [] and the others return null. Use listPolygons for the world-coordinate footprints that are always available.

Types

PluginSiteFootprintPoint

A 2D ground-plane point of a site parcel footprint, in world XZ plan coordinates (Snaptrude units) — the same plan space as a space's planPoints, so site parcels overlay space footprints directly.

Property	Type	Description
x	number	X coordinate (world, Snaptrude units)
z	number	Z coordinate (world, Snaptrude units)

PluginSiteGeoPoint

A geographic point of a site parcel ring (WGS84).

Property	Type	Description
lat	number	Latitude (degrees)
lng	number	Longitude (degrees)
alt	number	Altitude (metres)

PluginSitePolygon

A single site parcel/polygon. Its area is in the enclosing result's units.

Property	Type	Description
id	string	Unique parcel/component id
area	number	Footprint area, in the result's units
label	string	Parcel label / room type (e.g. "site")
footprint	PluginSiteFootprintPoint[]	2D ground-plane boundary points

PluginProgramSiteSnapshot

Result of get. Per the area-units convention, units sits on this snapshot and every area below is reported in it.

Property	Type	Description
units	"ft2" | "m2"	The unit all areas in this snapshot are reported in
totalArea	number	Total area of all site parcels
polygonCount	number	Number of site parcels
polygons	PluginSitePolygon[]	Each site parcel with its footprint

PluginSiteLatLng

A geographic latitude/longitude point (no altitude).

Property	Type	Description
lat	number	Latitude (degrees)
lng	number	Longitude (degrees)

PluginSiteBounds

Geographic bounds of the site terrain.

Property	Type	Description
north	number	North latitude
south	number	South latitude
east	number	East longitude
west	number	West longitude

PluginSiteContextParcel

A site parcel in the terrain context — geographic footprint and area.

Property	Type	Description
footprint	PluginSiteLatLng[]	Geographic boundary points
area	number	Parcel area (project area units)

PluginProgramSiteContext

The geo-referenced terrain context of the site.

Property	Type	Description
center	PluginSiteLatLng	Map center
bounds	PluginSiteBounds	Terrain bounds
widthInM	number	Terrain width in metres
heightInM	number	Terrain height in metres
zoom	number	Effective map zoom
parcels	PluginSiteContextParcel[]	Site parcels with geographic footprints

Functions

get()

Get a snapshot of the project site: the total site area, parcel count, and each parcel's footprint.

• Returns: PluginProgramSiteSnapshot — empty (zero totals, no parcels) when the project has no site.

const site = await snaptrude.program.site.get();
console.log(`${site.totalArea} ${site.units} across ${site.polygonCount} parcels`);

---

getArea()

Get just the total site area. A fast single-metric read — the same number as PluginProgramSiteSnapshot.totalArea, without computing the per-parcel footprints.

• Returns: { units: "ft2" | "m2", area: number } — area is 0 when there is no site.

const { area, units } = await snaptrude.program.site.getArea();
console.log(`Total site area: ${area} ${units}`);

---

listPolygons()

List the site parcels with their footprints (world XZ plan coordinates, Snaptrude units): each parcel's id, area, label, and 2D footprint (XZ ground-plane points).

• Returns: { units: "ft2" | "m2", polygons: PluginSitePolygon[] } — polygons is empty when the project has no site; each parcel's area is in units.

const { polygons, units } = await snaptrude.program.site.listPolygons();
for (const p of polygons) {
  console.log(p.label, p.area, units, `${p.footprint.length} boundary points`);
}

---

listGeoPolygons()

List the site parcels as geographic latitude/longitude rings. Only available when the project is geo-located on terrain; returns no rings otherwise. Use listPolygons for the scene-coordinate footprints that are always available.

• Returns: { polygons: PluginSiteGeoPoint[][] } — one ring of { lat, lng, alt } points per parcel; [] when the project is not geo-located.

const { polygons } = await snaptrude.program.site.listGeoPolygons();
if (polygons.length > 0) {
  const [firstRing] = polygons;
  console.log(firstRing.map(({ lat, lng }) => `${lat}, ${lng}`));
}

---

getContext()

Get the geo-referenced terrain context of the site: the map center and bounds, the terrain size in metres, the effective zoom, and each parcel's geographic footprint and area — the context used for site analysis.

• Returns: PluginProgramSiteContext | null — null when the project is not geo-located on terrain.

const ctx = await snaptrude.program.site.getContext();
if (ctx) {
  console.log(ctx.center.lat, ctx.center.lng, `${ctx.widthInM}m x ${ctx.heightInM}m`);
  for (const parcel of ctx.parcels) console.log(parcel.area, parcel.footprint.length);
}

---

getLocation()

Get the project's geographic location — the latitude/longitude the site is geo-located at, the location the analysis.* sun and daylight studies compute against. Returns null when the project is not geo-located on terrain (there is deliberately no fallback location).

• Returns: { latitude: number, longitude: number } | null

const location = await snaptrude.program.site.getLocation();
if (location) console.log(location.latitude, location.longitude);

---

getNorthAngle()

Get the site's true-north angle — the angle in degrees ([0, 360)) the model's north is rotated from true north, derived from the terrain's rotation — clockwise-positive viewed from above (the opposite sign convention to design.transform.rotate, where positive = counter-clockwise). 0 means the model is aligned to true north. Returns null when the project is not geo-located on terrain.

• Returns: number | null

const northAngle = await snaptrude.program.site.getNorthAngle();
if (northAngle !== null) console.log(`${northAngle}° from true north`);

---

Errors

Failed calls reject with a typed PluginError — see Error Handling. This namespace has no specific error conditions: every method is a total read — get returns an empty snapshot (zero totals) when there is no site, listPolygons/listGeoPolygons return [], and getContext returns null when the project is not geo-located.