POST /environment
Since 0.6
A partial sky merged onto the live one.
Goes through the simulation like the other mutating routes, because uploading a panorama and rebuilding the environment cube touch the renderer, which belongs to the sim thread.
Request
Request body: EnvironmentRequest
POST /environment request: a partial sky, merged onto the live one.
| Field | Type | Required | Description |
|---|---|---|---|
sky | SkyPatch | no | The sky fields to change. Absent leaves the sky alone. |
ambient | number | no | The flat ambient fill. Absent leaves it alone. |
Request body: SkyPatch
The sky fields a swap may set. Absent means "leave this one as it is".
| Field | Type | Required | Description |
|---|---|---|---|
kind | string | no | "procedural", "hdr", "color" or "atmosphere" (an atmosphere sky's own settings are written in the scene file). |
preset | string | no | A named procedural sky: clear-noon, golden-hour, overcast, dusk, night. Setting a preset with no kind switches to procedural, because that is the only thing a preset can mean. |
asset | string | no | The envmap asset id for an hdr sky. It must already be in scene.assets: this endpoint swaps skies, it does not add assets to a scene. |
intensity | number | no | Scalar on the whole environment. Free to change: no rebuild. |
rotation | number | no | Yaw applied to the whole sky, radians. Free to change: no rebuild. |
sun_from_sky | boolean | no | Whether the scene's directional light should follow the sky's sun. |
sun_elevation | number | no | Sun elevation above the horizon for a procedural sky, radians. Negative is below it. |
sun_azimuth | number | no | Sun azimuth for a procedural sky, radians. Setting either angle sets both, so a request giving only one keeps the other from the live sky. |
turbidity | number | no | Atmospheric haze for a procedural sky, within TURBIDITY_MIN..=TURBIDITY_MAX. |
Response
Response: EnvironmentResponse
POST /environment response: the environment after the swap, and where it went.
| Field | Type | Present | Description |
|---|---|---|---|
kind | string | always | "procedural", "hdr" or "color". |
preset | string | sometimes | The preset name, for a procedural sky. |
asset | string | sometimes | The asset id behind an hdr sky that loaded. |
asset_path | string | sometimes | The file that asset resolved to, as the engine opened it. |
intensity | number | always | Scalar on the whole environment. |
rotation | number | always | Yaw applied to the sky, radians. |
sun_direction | number[3] | sometimes | Travel direction of the sun the sky casts (sun -> scene), when it has one. A color sky has none. |
sun_color | number[3] | sometimes | Linear RGB of that sun. |
sun_intensity | number | sometimes | Its scene-referred irradiance. 0 when the sun is below the horizon. |
sun_from_sky | boolean | always | Whether the scene's directional light is following that sun. |
ambient | number | sometimes | The flat fill added on top of the image-based diffuse, when the scene has no sky field and ambient therefore still means what it meant before D7. |
findings | string[] | sometimes | Why this is not what the scene asked for: a missing panorama, an undecodable file. Empty when the sky is exactly what was written. |
persisted | boolean | always | Always false: this endpoint reports the live sky, and a live sky is never on disk until someone edits the scene file. Present so a client does not have to infer it. |
frame | integer | always | The frame the new sky is first drawn on. |
changed | string[] | sometimes | What was actually changed, so a caller sees that a field it sent was a no-op. |
Example
curl -X POST "http://127.0.0.1:7700/environment" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.