# GeoJSON 3D GLTF Generator API Spec

This API endpoint converts input 2D GeoJSON boundary data (Polygons or MultiPolygons) into a fully-structured, self-contained 3D GLTF 2.0 model containing extruded features, heights, and custom material settings.

- **Endpoint URL:** `http://localhost:8000/api/generate_gltf.php`
- **HTTP Method:** `POST` or `GET`
- **Access Control:** Supports CORS (`*`), and responds to preflight `OPTIONS` requests.

---

## 1. Request Parameters

The API accepts configurations via standard `POST` (JSON payload or `application/x-www-form-urlencoded`) or fallback `GET` query parameters:

| Parameter | Type | Required | Description | Default |
| :--- | :--- | :--- | :--- | :--- |
| `geojson` | `String` | **Yes** | A valid JSON string containing the GeoJSON feature collection or geometry. | - |
| `height_property` | `String` | No | The property key in feature attributes used to extract individual heights. | Uniform flat height (`2.0`) |
| `extrusion_scale` | `Float` | No | A multiplier applied to height mapping values to control vertical extrusion. | `10.0` |
| `base_color` | `String` | No | HEX code (e.g. `#00ffb2`) to set the base PBR material color of the extruded meshes. | `#00ffb2` |

---

## 2. Response Formats

The response format depends on the presence of the `action` query string parameter:

### 2.1 JSON Response (Default)
Returns a status indicator and the raw GLTF JSON object structure inside a `gltf` wrapper.

**Example Request:**
`POST /api/generate_gltf.php`

**JSON Response Schema:**
```json
{
  "status": "success",
  "gltf": {
    "asset": {
      "generator": "Glassbits PHP GLTF Generator v1.0",
      "version": "2.0"
    },
    "scene": 0,
    "scenes": [{"nodes": [0]}],
    "nodes": [...],
    "meshes": [...],
    "materials": [...],
    "buffers": [
      {
        "byteLength": 24904,
        "uri": "data:application/octet-stream;base64,AAAA..."
      }
    ],
    "bufferViews": [...],
    "accessors": [...]
  }
}
```

### 2.2 File Attachment Download
Prompts a standard browser download attachment named `geojson-3d-model.gltf` with Content-Type `model/gltf+json`.

**Example Request:**
`GET /api/generate_gltf.php?action=download&geojson={...}&base_color=%23ff0055`

---

## 3. Example Request Implementations

### 3.1 Fetch in JavaScript (Browser Client)
```javascript
const payload = {
    geojson: JSON.stringify(myGeojsonData),
    height_property: "population_density",
    extrusion_scale: 15.0,
    base_color: "#00ff7f"
};

fetch("http://localhost:8000/api/generate_gltf.php", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload)
})
.then(res => res.json())
.then(data => {
    if (data.status === "success") {
        console.log("Generated GLTF Model:", data.gltf);
    } else {
        console.error("Error:", data.message);
    }
});
```

### 3.2 Curl via Command Line
```bash
curl -X POST http://localhost:8000/api/generate_gltf.php \
  -H "Content-Type: application/json" \
  -d '{
    "geojson": "{\"type\":\"FeatureCollection\",\"features\":[{\"type\":\"Feature\",\"geometry\":{\"type\":\"Polygon\",\"coordinates\":[[[100,13],[101,13],[101,14],[100,14],[100,13]]]},\"properties\":{\"height\":5}}]}",
    "height_property": "height",
    "extrusion_scale": 12.0,
    "base_color": "#ff007f"
  }'
```

---

## 4. Technical Architecture details
1. **Mercator projection**: Coordinates are read, mapped flat, and translated into a standard 100x100 bounding box unit system centered on coordinates `(0, 0, 0)`.
2. **Ear-Clipping Triangulation**: Top and bottom polygon caps are triangulated using a classic ear clipping polygon tessellation loop on the backend.
3. **Double-sided Wall Panels**: Connecting vertical quads are automatically constructed between boundary nodes to represent 3D walls.
4. **Base64 binary packing**: Position coordinates (FLOAT) and index indices (32-bit UNSIGNED_INT) are packed using standard binary serialization (`pack`) and embedded as a base64 Data URI inside the single output `.gltf` file to preserve maximum compatibility and ensure no external file dependencies.