> For the complete documentation index, see [llms.txt](https://cityweft.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cityweft.gitbook.io/docs/basics/customizations.md). # Customizations Cityweft provides numerous opportunities for customizing output, allowing for tailored solutions that meet specific user requirements. All customization happens through the optional `settings` object in the body of a `POST /v1/context` request, plus the optional top-level `export` object for direct file export ([Exports](/docs/basics/exports.md)). ```json { "polygon": [[lat, lon], ...], "settings": { ... }, "export": { "format": "obj" } } ``` ## Choosing what geometry to receive | Setting | Description | Type / Values | Default | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------- | | `geometry` | Array of geometry groups to generate. Supported values: `buildings`, `surface`, `barriers`, `instances` (alias: `infrastructure`), `topography`. More detail: [Geometry](/docs/geometry/buildings.md) | `String[]` | `['buildings', 'surface', 'barriers', 'instances']` | | `surfaceTypes` | Which representations of the ground surfaces to return: `'meshes'` (the surface mesh group), `'centerlines'` and/or `'outlines'` (draped polylines). Any combination — without `'meshes'`, linework replaces the surface meshes. More detail: [Surface Lines](/docs/geometry/surface-lines.md) | `Array<'meshes' \| 'centerlines' \| 'outlines'>` | `['meshes']` | | `cropScene` | Slices the model to include only geometry inside the polygon boundary. Adds roughly 10–20% processing time depending on the area. | `Boolean` | `false` | {% hint style="info" %} `topography` is **not** included by default — add it to the `geometry` array (or set `topographyModel: true`) to receive terrain. {% endhint %} {% hint style="success" %} **New:** `surfaceTypes` — request road/path centerlines and surface outlines as draped polylines, alongside or instead of the surface meshes. See [Surface Lines](/docs/geometry/surface-lines.md). {% endhint %} ## Building defaults Applied only when the source data has no value for a building. | Setting | Description | Type / Values | Default | | -------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `defaultRoofType` | Roof type applied when the actual type is unknown. | `'flat'` \| `'hipped'` \| `'gabled'` \| `'onion'` \| `'dome'` \| `'round'` \| `'skillion'` \| `'mansard'` \| `'quadrupleSaltbox'` \| `'saltbox'` \| `'gambrel'` \| `'pyramidal'` | `flat` | | `defaultLevels` | Number of levels assumed when no height data exists. | `Number` | `1` | | `defaultLevelHeight` | Height of one level in meters, used to estimate total height when no data exists. | `Number` | `4` | ## Building data sources Cityweft combines worldwide base data with premium country datasets that carry measured heights and detailed roof shapes. By default, every request automatically uses **the best building data available to your account** — no configuration needed. | Setting | Description | Type / Values | Default | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------- | | `buildingSources` | `'all'` uses the best building data available to your account. `'global'` restricts the request to worldwide base data only. | `'all'` \| `'global'` | `'all'` | {% hint style="info" %} Premium country datasets require the matching **country add-on** on your plan. When a request touches a premium country you don't have access to, the response falls back to worldwide data and reports it in the `dataAccess` field: ```json "dataAccess": { "granted": "global", "suppressedCountries": ["US"], "reason": "country_access_required" } ``` Every building's `descriptor.datasetName` tells you which tier it came from — see [Metadata (Descriptors)](/docs/basics/metadata-descriptors.md). {% endhint %} ## Trees & vegetation | Setting | Description | Type / Values | Default | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------ | | `treeSource` | Tree data source: `'standard'` (surveyed points + procedural forest fill), `'hybrid'` (recommended — canopy-detected trees with measured heights and crown diameters), `'canopy'` (canopy-detected trees only). | `'standard'` \| `'hybrid'` \| `'canopy'` | `'standard'` | | `canopyMinHeight` | Shortest canopy counted as a tree, in meters. Applies to `'hybrid'`/`'canopy'`. | `Number` | `3` | | `canopyMinSpacing` | Minimum tree-to-tree spacing in meters for canopy detection. | `Number` | `3` | | `canopyMaxTrees` | Hard cap on the number of detected trees. | `Number` | `40000` | Full guide: [Trees & Vegetation](/docs/geometry/infrastructure/trees-and-vegetation.md) ## Topography & terrain projection | Setting | Description | Type / Values | Default | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------------- | | `topographyModel` | Includes the topography model in the output (equivalent to adding `'topography'` to `geometry`). | `Boolean` | `false` | | `topographyReturnType` | How terrain is returned. More info: [Topography](/docs/geometry/topography.md) | `'meshes'` \| `'elevationMap'` \| `'both'` | `'elevationMap'` | | `combineElevationMaps` | Merges the per-tile elevation maps into a single grid covering the whole site. | `Boolean` | `true` | | `projectToTopography` | Projects buildings, surfaces and barriers onto real terrain elevations **without** returning topography geometry. Useful when you need geometry to sit at real elevations but don't need the terrain mesh itself. | `Boolean` | `false` | | `disableSurfaceProjection` | Keeps surface geometry flat instead of draping it onto the terrain. | `Boolean` | `false` | ## Coordinates & output format | Setting | Description | Type / Values | Default | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | --------- | | `crs` | Coordinate reference system of the returned coordinates: `'local'` (meters from an origin), `'EPSG:3857'` (Web Mercator), `'UTM'` (auto-detected UTM zone). More info: [Coordinate Systems (CRS)](/docs/basics/coordinate-systems-crs.md) | `'local'` \| `'EPSG:3857'` \| `'UTM'` | `'local'` | | `upAxis` | Which axis represents "up" in the returned geometry, so it imports into your target application without manual rotation. | `'Y'` \| `'Z'` | `'Y'` | | `indexedMeshes` | Returns indexed meshes: vertices are welded and every mesh gains an `indices` array, significantly reducing payload size. JSON responses only — file exports are unaffected. | `Boolean` | `false` | {% hint style="success" %} **New:** `indexedMeshes` — with it enabled, render with `geometry.setIndex(mesh.indices)` in Three.js instead of expanding the triangle soup. {% endhint %} #### Example of a settings object ```json "settings": { "defaultRoofType": "gabled", "defaultLevels": 2, "defaultLevelHeight": 4.5, "geometry": ["buildings", "surface", "barriers", "topography"], "surfaceTypes": ["meshes", "centerlines"], "treeSource": "hybrid", "indexedMeshes": true, "cropScene": true } ``` *** ## Exporting to a file The `export` parameter turns a request into a direct file export — OBJ, Rhino, DXF, SketchUp, glTF, IFC, Revit and more — returning a download URL instead of JSON geometry, with optional real-world coordinate systems, placement and units. Full guide: [Exports](/docs/basics/exports.md)