> 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/geometry/surface-lines.md).

# Surface Lines

Surface lines are draped polylines — road and path centerlines, network outlines, and area boundaries — returned alongside or instead of the surface meshes.

{% hint style="success" %}
**New** — choose surface representations with the `surfaceTypes` setting.
{% endhint %}

Geometry Type: <mark style="color:blue;">`polylines`</mark>

```javascript
{
     "type": "surfaceLines",
     "geometryType": "polylines",
     "polylines": Polyline[]
},
```

### Request

The `surfaceTypes` setting selects which representations of the ground surfaces the response carries — an array, so any combination works:

```json
{
  "polygon": [[lat, lon], ...],
  "settings": {
    "surfaceTypes": ["meshes", "centerlines", "outlines"]
  }
}
```

| Value           | What you get                                                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `"meshes"`      | The regular surface mesh group — see [Surface](/docs/geometry/surface.md). **Default.**                                                                |
| `"centerlines"` | Draped centerline polylines of roads, paths, and waterways.                                                                                            |
| `"outlines"`    | The boundary of the drawn road network — matching the rendered road silhouette exactly, intersections included — plus boundary rings of area features. |

* Default (unset) is `["meshes"]` — exactly today's behavior.
* `["meshes", "centerlines"]` adds linework **alongside** the surface meshes.
* `["centerlines"]` or `["outlines"]` returns linework **instead of** the surface meshes.

All polylines are draped onto the terrain, follow the same `crs` / `upAxis` settings as the rest of the response, and are cropped by `cropScene` along the same boundary as the meshes.

### Polyline structure

```javascript
{
     "vertices": [x1, y1, z1, x2, y2, z2, ...],  // ordered points along the line
     "closed": false,                             // true for rings (outlines, boundaries)
     "descriptor": {
          "type": "path",              // same taxonomy as surface meshes
          "lineRole": "centerline",    // 'centerline' | 'outline'
          "pathType": "roadway",
          ...
     }
},
```

Descriptors keep the **same `type` values as the sibling surface meshes** (`path`, `water`, `pitch`, …), so linework can share your surface layer structure. `lineRole` distinguishes the representation:

| `lineRole`     | Meaning                                                             |
| -------------- | ------------------------------------------------------------------- |
| `'centerline'` | The feature's centerline (roads, paths, waterways)                  |
| `'outline'`    | The silhouette of the drawn network or the boundary ring of an area |

### Rendering in Three.js

```javascript
polylines.forEach((line) => {
  const geometry = new THREE.BufferGeometry();
  geometry.setAttribute(
    'position',
    new THREE.BufferAttribute(new Float32Array(line.vertices), 3)
  );
  const material = new THREE.LineBasicMaterial({ color: 0x222222 });
  const object = line.closed
    ? new THREE.LineLoop(geometry, material)
    : new THREE.Line(geometry, material);
  scene.add(object);
});
```

### File exports

Surface lines export as **native curves** in the formats that support them (DXF, 3DM, glTF, IFC), organized into per-type sublayers. In the `export` object, the single-value `surfaceType` chooses how ground surfaces are delivered (a file sensibly carries one representation per layer):

| `export.surfaceType` | Result                                          |
| -------------------- | ----------------------------------------------- |
| `'meshes'` (default) | Surface meshes                                  |
| `'centerlines'`      | Centerline curves **instead of** surface meshes |
| `'outlines'`         | Outline curves **instead of** surface meshes    |

See [Exports](/docs/basics/exports.md) for the full export options.