Infrared SDK

You give an area, your geometry and the analyses. The SDK on your machine cuts the area into tiles, sends one job for each tile to the Infrared cloud and merges the tile results. The cloud runs only the simulation models. A run engine in the Rust core decides every send, status check, download and retry. Python and TypeScript only do the network calls and the threads. You get the result of each analysis as soon as its last tile is merged, or all results at the end.

The inputs

• Area: one GeoJSON polygon in WGS84 ([lon, lat]).
• Your geometry: buildings, trees, ground materials, terrain, and context geometry. Context geometry is far objects that only give shade. The SDK does not analyse it. Only the sun and light analyses and the interior models take it, and it reaches 128 m past a tile.
• Weather: a weather file or a public weather station, and the time period.
• Analyses: one analysis or a list of analyses for the same area.
• Sensors (optional): the ground grid is the default. You can ask for sensors on facades and roofs (analysis_surfaces). Or give your own sensor points. Own points run as one job, not as an area run. See Bring your own sensors.

Use your own data. To start fast, you can also read public data for the area with the SDK.

The steps

1. Plan the tiles. The SDK cuts the area into tiles of 512 m. All analyses except wind read 128 m of geometry past each tile. Wind analyses move 256 m from tile to tile, so the tiles overlap by half. The SDK skips empty tiles. One run has a maximum of 100 tiles.
2. Prepare the geometry. The SDK prepares the site one time. Then it cuts your geometry for each tile.
3. Upload the geometry. The SDK uploads the geometry of each tile one time. All analyses on that tile use the same upload: ground and facade analyses share it. Wind analyses use their own tile grid, so they upload their own tiles. With a geometryUrlStore (TypeScript), a repeat run of the same area uploads nothing.
4. Submit the jobs. The SDK sends the jobs tile by tile, across all analyses. A tile goes out as soon as its upload is done. Each job has an idempotency key. If a submit gets no answer, the SDK sends it again with the same key: the job does not run or bill two times. A job that failed on the server is sent again as a new job, with a new key. On the binary transport, when the server offers it, the SDK sends the ready jobs together: up to 100 jobs (5 MiB) in one batch submit, at most 5 batches at the same time. A batch goes out as soon as a slot is free; the first jobs do not wait for a full batch. Each job in a batch keeps its own key and its own charge, and the rules above stay the same for each job. A job the batch does not take is sent alone. To send one request per job, pass batch_submit=False (Python) or batchSubmit: false (TypeScript) to the client.
5. Wait. The SDK asks for the job status while it still sends. The first check is 0.5 s after the first job is accepted; a job accepted later is asked in the next check. Then one request asks for the status of up to 50 jobs: every 0.25 s up to 4 s, every 0.5 s up to 10 s, then every 2 s. So 81 jobs need 2 requests for each check, not 81. A check sends at most 8 of these requests each second, so a check of up to 400 jobs keeps this rhythm. Without the batched route, the SDK asks for each job with at most 2 requests each second. A status request that fails is asked again.
6. Download the results. The SDK downloads each result when its job is done, while other jobs still run and while uploads continue. The results come back in a binary format by default.
7. Merge. The SDK joins the tiles on your machine. It merges each result when its download is complete, in the background. An analysis is ready when its last tile is merged. Wind tiles are blended in the core at the end of the analysis.

Steps 2 to 7 do not wait for each other. Each tile goes on as soon as it is ready. The engine sets how many requests run at the same time (32 submits, or 5 batch submits, 16 status requests, 13 downloads). This is not a limit on the jobs that run in the cloud: more jobs can run at the same time. Python and TypeScript work the same way. max_workers (maxWorkers) has no effect and is deprecated.

Get each result when it is ready

If you run more than one analysis, you do not have to wait for the last one. run_area_iter (runAreaStream) gives each analysis when its last tile is merged. The order is the order in which they finish, not the order of your list. Each item has the index in your list, the analysis type, and the result or an error. A failed analysis is an item with an error: the others continue. The SDK keeps no reference to a result after it gives it to you, and it frees the tile bodies and the merge buffer of each finished analysis, so read the items one by one. At most two analyses of one run, and six over all runs in one process, merge at the same time. An analysis frees its slot when you take its item, so a stream that you stop reading (and do not close) makes other runs wait. If you leave the loop early, the run stops and sends no more tiles. Jobs that the cloud has already accepted are not cancelled.

for item in client.run_area_iter([solar, wind], polygon, buildings=buildings):
    if item.error is None:
        draw(item.index, item.result)

for await (const item of client.runAreaStream([solar, wind], polygon, { buildings })) {
  if (item.error === undefined) draw(item.index, item.result);
}

run_area_and_wait (runAreaAndWait) gives all results at the end. Give it the list of analyses: ONE call runs them as one run. They share the prepared site and each facade tile's parts, and you get one result for each analysis, in the order of your list. If an analysis fails, the call throws the first error in list order after the others are finished. Do not make one call for each analysis: each call prepares the site again.

solar_result, wind_result = client.run_area_and_wait([solar, wind], polygon, buildings=buildings)

const [solarResult, windResult] = await client.runAreaAndWait([solar, wind], polygon, { buildings });

run_area (runArea) also takes a list and gives one schedule for each analysis. Stream and wait use the default wind merge. For the directional blend, use run_area (runArea) and merge_area_jobs (mergeAreaJobs) with a strategy. retry_from (retryFrom) is not an option of the stream or of a list: retry each analysis alone with run_area (runArea). In Python, merge_area_jobs also takes the list of schedules and gives a list of results in the same order; in TypeScript, merge one schedule at a time.

To stop a stream early in Python, leave the loop (break) or call close() on the object run_area_iter returns; close() is safe from any thread, and a loop that waits for an item then ends. In TypeScript, use signal.

When a tile fails

A failed tile does not stop the other tiles. The SDK never gives you a result with holes. In run_area_and_wait (runAreaAndWait) and in the stream, the engine sends a failed tile again as a new job, one time by default (retries=1). If a tile still fails, an analysis with a missing tile gives an error and no result. run_area_and_wait raises an error that names the tiles (Python: AreaRunError, with failed_tiles). The stream gives an item with error. A status answer 401 or 403 stops the run. For run_area (runArea) and the retry keys, read Cost and retry.

Example: one run

import os

from infrared_sdk import InfraredClient, parse_epw
from infrared_sdk.analyses.types import (
    AnalysesName, UtciModelBaseRequest, UtciModelRequest,
)
from infrared_sdk.models import Location, TimePeriod

client = InfraredClient(api_key=os.environ["INFRARED_API_KEY"])

payload = UtciModelRequest.from_weatherfile_payload(
    payload=UtciModelBaseRequest(analysis_type=AnalysesName.thermal_comfort_index),
    location=Location(latitude=48.21, longitude=16.37),
    time_period=TimePeriod(start_month=7, start_day=15, start_hour=12,
                           end_month=7, end_day=15, end_hour=16),
    weather_data=parse_epw("vienna.epw"),
)
result = client.run_area_and_wait(
    payload, polygon,
    buildings=buildings,        # your meshes, in metres
    vegetation=trees,           # your trees
    ground_materials=ground,    # your ground layers
)

import { InfraredClient, initializeCore } from "@infrared-city/infrared-sdk";

await initializeCore();
const client = new InfraredClient({ apiKey: process.env.INFRARED_API_KEY });

const result = await client.runAreaAndWait(
  {
    analysisType: "thermal-comfort-index",
    latitude: 48.21, longitude: 16.37,
    dateFilters: { period: { start: { month: 7, day: 15, hour: 12 },
                             end: { month: 7, day: 15, hour: 16 } } },
    weather: client.weather.parseEpw(epwText),
  },
  polygon,
  { buildings, vegetation: trees, groundMaterials: ground },
);

Terrain goes in the analysis request as ground_geometry (groundGeometry). Context geometry goes in the request of a ray-traced solar or interior analysis as context_geometry (contextGeometry).

Reference

• Python: the client, run_area_and_wait and run_area.
• TypeScript: the SDK reference, InfraredClient.runAreaAndWait and InfraredClient.runArea.

You give the area as a polygon in lon/lat. You give your geometry in metres. The SDK moves every layer into the frame of each tile. Most wrong results come from a wrong frame, so read this page once.

The rules

1. The area is a polygon in lon/lat (WGS84, [lon, lat]). Use one ring, no holes, no self-crossing.
2. The south-west corner of its bounding box is the origin (0, 0, 0) of your model: the smallest lon and the smallest lat.
3. Your model is in metres. x is east, y is north, z is up. z is the height above the ground.
4. Keep every coordinate below 100,000 m in size (absolute value). Do not send UTM or other absolute coordinates. The SDK refuses them.
5. Trees and ground materials are in lon/lat, not in metres.

Buildings, terrain and context geometry share the metre frame.

The SDK moves it for you

Each tile has its own frame. The SDK moves every metre layer from the site frame into each tile frame. You do not do this.

A bare buildings map has no frame. The SDK reads it as "already in the frame of the run polygon". An acquired buildings object keeps its origin. So pass the object that you got:

• You get buildings for polygon A and run polygon B with the bare map: the whole city moves by the distance between the two south-west corners.
• You pass the acquired object: the SDK moves it from its own origin. One acquisition for a large polygon can serve several smaller runs.

What the SDK refuses

The SDK stops with an error, before you pay, when:

• the polygon is wrong, or a coordinate is not finite;
• a mesh has no indices;
• a ground layer name is unknown, or a terrain sheet is wrong;
• a tile coordinate is 100,000 m or more;
• you give more than 300,000 own sensor points.

Silent traps

The SDK does not catch these. The run is billed and the result is wrong.

Check your model in a viewer before you run. A building that stands at the right place and has the right height is a good sign.

Example: coordinates

buildings = client.buildings.get_area(polygon)   # keeps its origin
result = client.run_area_and_wait(
    payload, polygon,
    buildings=buildings,          # pass the object, not buildings.buildings
)

const buildings = await client.buildings.getBuildingsInArea(polygon);
const result = await client.runAreaAndWait(
  request, polygon,
  { buildings },                  // pass the object, not its inner map
);

Learn more

• Your inputs: all the layers and the weather.
• How a run works: the tiles and the steps.
• Python: the client. TypeScript: the SDK reference.

The SDK cuts your area into square tiles. It sends one job for each tile. Tiles are 512 m wide. The step from tile to tile depends on the analysis. This page shows how the grid looks and what it means for your results.

Two tile families

• Solar family: all tiled analyses except wind. The step is 512 m, so tiles do not overlap. Each tile also reads geometry 128 m past its edge.
• Wind family: wind speed and pedestrian wind comfort. The step is 256 m, so neighbour tiles overlap by 50 % each way. Wind tiles read no extra margin.

Each family has its own grid. Analyses of one family share it. A run with a solar analysis and a wind analysis uses both grids.

Empty tiles and the tile limit

• A tile that does not touch your area is empty. The SDK skips it and sends no job.
• One run has a maximum of 100 non-empty tiles. A larger area needs an explicit yes: max_tiles_override (maxTilesOverride).

How the tiles join

Wind tiles overlap, so the SDK must choose which values to keep.

• Default: the SDK keeps the centre 256 m of each tile. The centres fit together with no gap. The core joins the wind tiles at the end of the analysis.
• Directional blend: an option for wind speed only. It needs the wind direction. Use run_area (runArea) and then merge_area_jobs with strategy="directional_blend" and wind_direction_deg (TypeScript: strategy, windDirectionDeg). run_area_and_wait, run_area_iter and runAreaStream use the default merge.

Your own model is the normal input. Give the layers that you have. Each layer has a fixed shape. Weather and a time period come on top.

Your model, layer by layer

• Buildings: closed meshes {id: {coordinates, indices}} in metres (x east, y north, z up). Each building is one closed solid with a bottom face. All outdoor analyses read them. Facade and roof sensors come from them.
• Trees: {id: GeoJSON Point} in lon/lat, with genus, height and crownDiameter (metres). The genus sets the crown shape. Height and diameter are optional: a tree with none gets 6 m height and 4 m crown, and gives no warning. An unknown genus is a broadleaf tree. A point can have a height: [lon, lat, z], with z in metres in the frame of the buildings and the terrain. Under terrain_alignment "as-is" the tree stands at its z. The other modes do not use z. Under "as-is" with terrain, a tree with no z stands at z = 0, and the SDK logs one warning with the count.
• Ground materials: one GeoJSON FeatureCollection in lon/lat for each layer: asphalt, concrete, soil, vegetation, water. An unknown layer name is an error. Only the thermal comfort analyses read them.
• Terrain: a triangle mesh in the frame of the buildings, in ground_geometry (groundGeometry). There is no input for a height map: make a mesh first. Maximum 500,000 triangles in one request. terrain_alignment sets how your buildings and trees meet it: "as-is" (default), "auto-align" or "assume-aligned". Wind analyses refuse terrain.
• Context geometry: far objects that only give shade, in context_geometry (contextGeometry). The SDK does not analyse them. The four sun and light analyses and the interior models take them. Wind and thermal comfort do not. A request with context geometry also needs terrain, facade or roof sensors, or your own sensor points: on its own it is refused.

Meshes are in metres. See Coordinates for the frame.

Context geometry: the reach and the hole

A context mesh goes to a tile job when it stands less than context_reach_m (contextReachM) outside that tile. The default is 600 m. An object that is farther away is not sent: it gives no shadow and no error (the SDK logs its id). None (null) sends every mesh to every tile job. A number must be larger than the tile margin plus the buffer below (138 m for the sun and light analyses with the default buffer): a smaller reach is an error.

Each tile job already holds your detailed buildings up to the tile margin (128 m for the sun and light analyses). Context is not sent in that area plus a buffer of context_buffer_m (contextBufferM, default 10 m), so context never overlaps your detailed buildings.

When you pass your own buildings, give them for every tile plus the tile margin (128 m). The tiles cover the site in steps of 512 m, so this area can reach past the site edge. It is the area the SDK reads when you pass no buildings. Context geometry is only for what is outside that area: a building that is only in the context and stands in a tile or its margin is removed from that tile job, and nothing replaces it.

• The context triangles in this area are removed from that tile job; the rest of each mesh stays. So a merged city mesh, or a sheet like ground_geometry given as context, keeps its parts outside the area. The SDK logs one warning with the count: put close neighbours in buildings.
• context_buffer_m=0 (contextBufferM: 0) removes only the tile and its margin.
• Your ground_geometry is separate: the SDK cuts it per triangle for each tile, as before.
• A context mesh with no readable coordinates (empty, or NaN) stops the run before any job, with an error that names the mesh.

A tile job carries at most 250,000 context triangles. Above that the run stops with an error that names the count. A longer reach sends each mesh to more tile jobs, so keep far geometry sparse and low-poly: simple blocks for far buildings and hills; simplify_meshes (simplifyMeshes) makes a mesh coarser (see below).

Make geometry light: weld, simplify, export

Context geometry gives shade only, within context_reach_m (above). A detailed model costs upload bytes in every tile job it reaches and gives almost the same shadow. The same holds for a detailed terrain: give terrain as ground_geometry (groundGeometry, at most 500,000 triangles) and far objects as context_geometry (contextGeometry). Make both light once: weld, simplify, look at the result, and pass it straight in. Each step takes a whole geometry dict in one call (for one mesh, a dict with one entry), and each mesh stays a separate mesh. Weld and simplify return the dict as flat arrays (geometry) and the counts per mesh (report): triangles and vertices in and out, and the simplifier's error.

1. Weld: weld_meshes (weldMeshes). Many exports (Grasshopper, Rhino) write each triangle with its own corners, and the copies of one corner are not always identical. tolerance_m (toleranceM, default 0: identical positions only) is the largest distance between two copies of one corner. Keep it well below the smallest real edge. No vertex moves and the shape stays the same; the mesh gets smaller.
2. Simplify: simplify_meshes (simplifyMeshes) removes detail. max_error_m (maxErrorM, default 1 m) is the error limit; target_ratio (targetRatio) limits the kept share of the triangles. The first limit met stops it. The copy keeps a subset of your vertices with their exact values.
   • The error is typical, not a bound. Most of the surface stays within max_error_m, but single points can be 2 to 3 times as far. A thin part (a mast, an antenna) becomes a line.
   • lock_border (lockBorder, default on) keeps the rim of a terrain sheet, so it still meets its neighbour. Turn it off for buildings with an open base: they then simplify further.
   • A mesh that collapses to no triangle (a thin wall with lock_border off) is left out of the result. Compare the number of meshes in and out to see how many.
3. Export (to look at it or keep it): export_meshes (exportMeshes) writes "dotbim" (default: the open mesh format of the Grasshopper, Blender and Speckle plugins, in metres, Z up, site frame), "obj" (Rhino opens it without a plugin) or "json" (the SDK dict: load it and pass it back later). The SDK reads back only "json".
4. Pass it straight in: the geometry of a result goes into the payload as it is. No file is needed in between.

For example, a 1,000,000-triangle terrain becomes 10,000 triangles in less than a second, and 640,000 triangles of detailed city buildings become 112,000 at 1 m with lock_border=False.

from infrared_sdk.geometry import export_meshes, simplify_meshes, weld_meshes

terrain = simplify_meshes(weld_meshes(dem_mesh, tolerance_m=0.001).geometry,
                          max_error_m=0.5)
far = simplify_meshes(weld_meshes(far_buildings, tolerance_m=0.001).geometry,
                      lock_border=False)
print(far.report)                              # triangles in and out per mesh
with open("far-context.bim", "w") as f:
    f.write(export_meshes(far.geometry))       # look at it (dotbim)

payload = SvfModelRequest(analysis_type=AnalysesName.sky_view_factors,
                          analysis_surfaces="all",
                          ground_geometry=terrain.geometry,
                          context_geometry=far.geometry)

import { exportMeshes, simplifyMeshes, weldMeshes } from "@infrared-city/infrared-sdk-ts";

const terrain = simplifyMeshes(weldMeshes(demMesh, { toleranceM: 0.001 }).geometry,
                               { maxErrorM: 0.5 });
const far = simplifyMeshes(weldMeshes(farBuildings, { toleranceM: 0.001 }).geometry,
                           { lockBorder: false });
console.log(far.report);                                  // triangles in and out per mesh
await writeFile("far-context.bim", exportMeshes(far.geometry)); // look at it (dotbim)
const payload = { analysisType: "sky-view-factors", analysisSurfaces: "all",
                  groundGeometry: terrain.geometry, contextGeometry: far.geometry };

Bring your own sensors

The ground grid is the default. You can choose where the values are:

• Facades and roofs: analysis_surfaces (analysisSurfaces) is "facades", "roofs" or "all". surface_grid_size (surfaceGridSize) sets the cell size in metres (default 2.0, minimum 0.25). surface_offset (surfaceOffset) sets the distance from the surface (default 0.1 m). This is an area run. See Facades and roofs.
• Your own points: sensor_points (sensorPoints) is a list of [x, y, z] points in metres, in the frame of your geometry. The list must not be empty and has at most 300,000 points for each job. sensor_normals (sensorNormals) is optional: one non-zero normal [x, y, z] for each point, in the same order. You cannot use analysis_surfaces and sensor_points in one request.

Both work on the four sun and light analyses: solar radiation, sky view factor, direct sun hours and daylight availability. Thermal comfort and wind take no own sensors. The interior daylight factor takes sensor_points and sensor_surfaces too. See Interior.

Own points are not an area run: run_area and run_area_and_wait (runArea, runAreaAndWait) refuse them. The SDK does not tile them. Send your geometry with them in one request, and call client.analyses.run_and_wait(request) (TypeScript: client.runAndWait(request)). The result is a flat list with one value for each point, under the key output.

request = SvfModelRequest(
    analysis_type=AnalysesName.sky_view_factors,
    geometries=my_tower,                   # your meshes, in metres
    sensor_points=[[110, 90, 1.5], [110, 130, 15]],
    sensor_normals=[[0, -1, 0], [0, 1, 0]],
)
result = client.analyses.run_and_wait(request)
values = result["output"]                  # one entry for each point

const result = await client.runAndWait({
  analysisType: "sky-view-factors",
  geometries: { tower: { coordinates, indices } },
  sensorPoints: [[110, 90, 1.5], [110, 130, 15]],
  sensorNormals: [[0, -1, 0], [0, 1, 0]],
});

Weather and time period

Thermal comfort, solar radiation and energy balance read weather.

SDK 1.0 has ten analyses. Eight are outdoor analyses. They run on an area, and the SDK cuts the area into tiles. Two are interior analyses. They are Beta. You can run several outdoor analyses in one call.

Outdoor wind

• Wind speed: the wind speed at each point, for one speed and one direction. Pick them from the weather file or set them. It takes no terrain.
• Pedestrian wind comfort: a comfort class for a criterion that you select. You give the hourly wind speeds and directions from the weather file. It takes no terrain.

Outdoor sun and light

• Solar radiation: the solar radiation over a time period.
• Sky view factor: how much open sky each point sees. It needs no weather and no time period.
• Direct sun hours: the hours of direct sun over a time period.
• Daylight availability: the share of daylight over a time period.

Only these four give values on facades and roofs. They also take your own sensor points (sensor_points, up to 300,000 for each job) and give one value for each point. See Bring your own sensors.

Outdoor thermal comfort

• Thermal comfort index (UTCI): the perceived outdoor temperature over a time period.
• Thermal comfort statistics: the percent of time in comfort, heat stress or cold stress.

Daylight factor and energy balance (Beta)

• Daylight factor: rooms: the daylight factor at sensor points in rooms, under a CIE overcast sky. A large floor runs in parts.
• Daylight factor: your sensors: the same overcast-sky method on sensors that you give: your own points (sensor_points), or your own horizontal surfaces, for example a roof (sensor_surfaces). It is not an area run.

Daylight availability (above) and the daylight factor are two different methods. Daylight availability uses the sun and the sky over a time window. The daylight factor uses a standard overcast sky and needs no time.

• Energy balance: the monthly heating and cooling energy need of each zone. Run one building in one request.

Interior analyses do not run as an area run.

All analyses at a glance

The tiling family sets the tile step and the context around each tile. See Tiling and context.

Learn more

• Your model: the inputs each analysis reads.
• Weather and time period: the weather columns.
• Results: read real values, for example UTCI.
• Interior analyses: daylight factor and energy balance.
• Facades and roofs: runs with values on surfaces.
• API reference: Python and TypeScript.

Two interior models run on one building and not on an area: daylight factor and energy balance. Both are in Beta. You send the walls, slabs and windows. run_area refuses them.

Daylight factor: the inputs

The model gives the daylight factor in % under a CIE overcast sky. It has no date and no time.

1. barriers: the walls and slabs (category "wall" or "floor").
2. openings: the windows (category "window"). A window can carry its own light transmittance from 0 to 1 (opening_factor= in interior_entities). Without it, glazing_transmittance applies (default 0.63).
3. spatial_volumes (optional): one closed volume for each room (category "space"), for results for each room.
4. floors: the storeys to calculate, by index or by UUID.
5. The sensors: a grid on each floor (grid_size, default 0.5 m; analysis_height, default 0.8 m), or your own sensors (see "Your own sensors" below).
6. context_geometry: neighbours that only give shade. Without them the rooms read too bright. ground_geometry holds the terrain.
7. room_reflectances: floor 0.2, walls 0.5, ceiling 0.7 by default.

The result is one value for each sensor point. With rooms, you also get the mean, minimum, maximum and the share of area at 2 % or more for each room.

Your own sensors

Bring your own sensors instead of the floor grid. This also works outside a room: the same overcast-sky method, for example on a roof.

• sensor_points (sensorPoints in TypeScript): a list of [x, y, z] points in metres. The result has one value for each point.
• sensor_surfaces (sensorSurfaces): your own meshes by id. The model puts a sensor grid on them. The server refuses a surface that is not horizontal, so a facade does not work here. For facades, use an outdoor analysis with analysis_surfaces.
• If you send both, sensor_points wins and sensor_surfaces is ignored. The SDK refuses this. With either one, floors is ignored: the SDK refuses floors, floor_index and floor_uuid next to them.
• A request with your own sensors is one job. The SDK does not split it into parts.
• Add context_geometry for the neighbours that give shade. Barriers are optional when you bring context_geometry, ground_geometry or trees.

An area run gives one merged result. A facade or roof run gives one value for each surface cell. An interior run gives one value for each sensor point. In all cases, read the values with the helper of the SDK. The helper gives you the real values, whatever type the server used to send them.

Three shapes

1. Ground grid (area runs). The SDK merges the tiles and clips the result to your area. You get one map with cells of 1 m. A cell outside the area has no value.
2. Facades and roofs (surface runs). You get one value for each cell of each surface, in columns.
3. Interior points (daylight factor). You get one value for each sensor point. Each point has a room, or no room. See Interior.

A facade or roof run puts sensors on the walls and roofs of your buildings. It gives one value for each sensor cell. Only solar radiation, sky view factor, direct sun hours and daylight availability run on surfaces. Set analysis_surfaces (analysisSurfaces) to "facades", "roofs" or "all". The sensors replace the ground grid.

Only the buildings inside your area polygon get sensors. A building is a target when the centre of its bounding box is inside the polygon. Each building therefore belongs to one area, and two areas that touch never count it twice. A building that you pass in but that is outside the polygon is not removed: it stays in the scene as shade, and it gets no sensors and no result surfaces. A 20 m polygon around one building gives the surfaces of that building only, even if you pass in the whole district. Ground analyses do not change.

Batches

1. Sensors. The SDK puts a grid of sensor cells on the walls and roofs of the target buildings of each tile (the buildings inside the polygon).
2. Batches. The SDK puts the buildings into batches by sensor count. With packing="regular" (the default) a batch has at most 250,000 sensors, and the SDK counts the sensors of each batch exactly and groups the buildings by building id. With packing="fast" it counts each building one time, alone, and fills each batch up to 290,000 sensors by those counts, in the order of the building ids. Fast plans in less time and usually makes fewer, fuller jobs. The result is the same: the cells of a building, their keys and their values do not depend on the batch of the building, only on the building and the terrain.
3. One job for each batch. Each job is billed. A tile with no target building sends no job and costs nothing.
4. The scene. When the server supports it, the SDK uploads the scene of a tile one time. The jobs of the tile use that upload. With the default packing, the scene is the same file as the tile of a ground analysis: a run with ground and facade analyses uploads each tile one time. This is true for both packings.
5. Shade. Neighbour buildings (outside the polygon) and the buildings of other batches only give shade. They get no result. A building has the cells of its own geometry only: a cell that a neighbour hides, even a cell inside the neighbour, keeps its sensor and is simply dark. Only a cell inside the building itself, or below the ground, has none.
6. Merge. The SDK joins the batches into one result.

To see the number of jobs before you run, use preview_area(..., payload=...) and read would_bill_jobs. Without payload=, the facade count is too low.

The plan depends only on the geometry and the surface settings (grid size, offset, mesh cleaning, terrain alignment, max_sensors_per_job, packing), not on the analysis or the weather. The SDK makes it one time and keeps it in the client: the analyses of one call share it, and a later run or preview on the same geometry uses it again. The facade analyses of one call (run_area_and_wait([...]), runAreaStream([...])) also share each job's geometry: the SDK writes it one time for all of them.

The SDK runs on your machine. Only the simulation models run in the Infrared cloud. This page shows where the SDK can run.

One core

The SDK has one core, written one time in Rust. Python and TypeScript use the same compiled core for the hard steps: tiling, geometry preparation, packing and merge. The same core also runs the engine that decides every send, status check, download and retry. You get the same result and the same retry rules in Python and in the browser.

Your machine sets the speed of these steps. The network and the cloud models set the rest. Measured on 2026-10-07 (1.0.0 packages, production API): one square kilometre of Vienna (4,212 buildings, own data) with sky view factor, wind and UTCI in one Python call took 8.7 s.

Python

• The engine sets the number of requests at the same time: 32 submits (or 5 batch submits), 16 status requests, 13 downloads. Python decodes and merges at most 8 tiles at the same time: that is CPU work, and more threads only use more memory. You set no thread count for the run. max_workers has no effect and is deprecated.
• The merge runs in the background while the jobs run.

Node.js

• Use Node 18 or later. The engine sets the requests at the same time, the same as in Python. maxWorkers has no effect and is deprecated. A network call does not block the JavaScript thread.
• Call await initializeCore() one time before a run call (runArea or runAreaAndWait). Without it, a run call throws CoreNotReadyError. Only the public site reads (buildings.getBuildingsInArea, vegetation.getArea, groundMaterials.getArea) load the core by themselves.
• On Node 22 or later, the core uses threads by default: min(4, cores) (8 from 16 cores) worker threads (the Rust rayon pool). On Node 18 and 20, and on a machine with one core, it uses one thread. The results are the same bytes either way.
• To use one thread, or another count, say so before any other SDK call:

await initializeCore({ threads: 1 }); // one thread
await initializeCore({ threads: 8 }); // eight threads

The threads decode and merge the result tiles, zip the request bodies, prepare the site, and build the facade captures, layouts and joins. This work does not block the JavaScript thread: the SDK waits for the pool with Atomics.waitAsync, so sends, polls, downloads and your own timers go on. With one thread, the core runs each call at once, as before. All the downloads of one moment go to the core in one call. 13 analyses, 625 jobs in one stream (fake gateway, build-box, 2026-10-09): 12 s with 4 or 8 threads, 18-20 s on one thread. Threads do not speed up network calls. A core error on a thread is a thrown error, and the process continues. Only running out of WebAssembly memory (near 4 GiB) ends the process.

Module format. The package is ESM. CommonJS require() works for the root entry only. The types are in the package: use TypeScript 5.4 or later (5.8 for CommonJS).

TypeScript in the browser

The browser runs the core on one thread and needs no special headers. Use a Web Worker to keep the page free.

1. In the worker file, call serveSdkWorker().
2. On the page, call createWorkerClient. Compile the WASM module one time and give it to the worker. Call initializeCore on the page and in each worker: each has its own core.
3. Put your API key in a proxy on your own origin. The browser never holds it.
4. Optional: pass a geometryUrlStore that you own. A new worker then does not upload the tiles again. A repeat run of the same area then uploads nothing.

// sdk.worker.ts
import { serveSdkWorker } from "@infrared-city/infrared-sdk/worker";
serveSdkWorker();

// page
import { createWorkerClient } from "@infrared-city/infrared-sdk/worker";
const sdk = createWorkerClient({
  worker: new Worker(new URL("./sdk.worker.ts", import.meta.url), { type: "module" }),
  module,                                    // the compiled WASM module
  config: { baseUrl: `${location.origin}/infrared-api` }, // your proxy
  getToken: () => session.accessToken(),     // your session, not the API key
});

For the proxy and the save and reload steps, read Serve many users.

Use this guide when many people use your app to run facade or roof analyses and look at the results. You choose where the SDK runs. Both ways use the same SDK calls and saved formats. For the runtimes, read Where it runs.

Two ways

You can mix the two. A result that a server made can be drawn in a browser, and the other way round.

Never send the API key to a browser. In both ways the key stays on your server.

A. In the browser

The SDK runs in one Web Worker on the user's device. Use one client for each tab. It keeps the geometry once for all analyses of that user. For the worker code, read Where it runs.

The browser must call the API through a proxy on your own origin. The proxy:

1. Checks that the user is signed in (your own check).
2. Optionally counts the runs of the user against a quota.
3. Replaces the Authorization header with your key (X-Api-Key).
4. Forwards the request to https://api.infrared.city/v2.
5. Also relays the storage URLs for upload and download, because the browser blocks them. The code below does not show this. See "Calling the API from a browser page" in the TypeScript README.

// A small proxy. Any server or edge function that can forward a request works.
// Add the relay for the storage URLs (step 5) yourself.
export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    if (!url.pathname.startsWith("/infrared-api/")) return new Response("Not found", { status: 404 });
    const user = await verifySession(request.headers.get("Authorization"), env); // your check
    if (!user) return new Response("Forbidden", { status: 403 });
    const headers = new Headers(request.headers);
    headers.delete("Authorization");
    headers.set("X-Api-Key", env.INFRARED_API_KEY); // a secret on the server only
    const target = "https://api.infrared.city/v2/" + url.pathname.slice("/infrared-api/".length) + url.search;
    return fetch(target, { method: request.method, headers, body: request.body });
  },
};

The SDK has no per-user API key. To limit each user, count in the proxy.

B. On your server

Use one client for each process. A second client holds the geometry again.

import os
from infrared_sdk import InfraredClient

client = InfraredClient(api_key=os.environ["INFRARED_API_KEY"])

import { InfraredClient, initializeCore } from "@infrared-city/infrared-sdk";

await initializeCore(); // threads by default on Node 22+
export const client = new InfraredClient({ apiKey: process.env.INFRARED_API_KEY });

• The client keeps the geometry of each facade or roof job in its own memory. Analyses on the same geometry share one copy.
• Submit and merge with the same client, in the same process. A schedule that another process merges gives a result with no outline. That process needs a saved layout.

Save and reload

Save two things in your own storage:

• The layout, one time for each geometry: layout.toBytes() and layout.layoutKey.
• The values of each result: surfaceColumnsToBytes(columns, { layoutKey }) (Python: columns.to_bytes(layout_key=...)).

To reload, load both (FacadeLayout.fromBytes, surfaceColumnsFromBytes), check them with attachValues, and call surfaceRenderBuffers(columns, { layout }). To rebuild the layout of an older run, pass the surfgridVersion (surfgrid_version) of that run. Leave emitCellTris off: it makes the layout about three times larger. For the code and the drawing steps, read Render buffers in detail.

Reuse uploads across reloads and workers

The SDK keeps the URL of each uploaded tile geometry in memory. A new worker or a page reload uploads all tiles again. A geometryUrlStore that you own keeps the URLs, so the same geometry is not uploaded twice. With the store, a repeat run of the same area sends no upload at all: the SDK reads each URL from the store and posts the jobs at once.

const geometryUrlStore = {
  async get(key: string) { return await idbGet(key); }, // { url, expiresAt } or undefined
  async set(key: string, url: string, expiresAt: number) {
    await idbPut(key, { url, expiresAt });
  },
};
serveSdkWorker({ geometryUrlStore /* , ...other options */ });

idbGet and idbPut stand for your own IndexedDB store.

• One store serves every worker of the session. Two workers that miss the same tile at the same time both upload it, unless the store also has a claim(key) (for example a Web Lock, see the TypeScript README): then one worker uploads and the other reads its URL.
• The SDK makes the keys from a digest of the credentials. A renewed token gives a new key. Keep one store for each user.
• An entry expires after 23 hours. A refused URL is uploaded again by the SDK.
• An entry is a read link: delete the store at sign-out.
• Python keeps URLs in memory until they expire (the link lasts about 24 hours) and has no store option.

Clean up and limit

• Free the geometry of a schedule that you drop: client.jobs.captures.forgetSchedule(schedule) or client.forget_schedule(schedule).
• runAreaAndWait frees the jobs of a failed or aborted run itself.
• At exit, call client.jobs.captures.free() (TypeScript) or client.close() (Python).
• A merge of a large site uses much memory for a short time. A 4 km city facade run (about 400,000 surfaces) peaked at about 3 GB. Run 1 or 2 merges at a time in one process, and measure your own sites.
• On Node, the threaded core ends the process only when it runs out of WebAssembly memory (near 4 GiB). Other core errors are thrown errors.

Checklist

• The API key is only on your server.
• Browser way: one worker client for each tab.
• Server way: one client for each process.
• The layout is saved one time for each geometry, with its layoutKey.
• Abandoned schedules go to forgetSchedule (forget_schedule).

One tile is one billed job. This page shows how to count the jobs before you run, what happens when a tile fails, and how the SDK keeps a retry from billing a job two times.

What is one job

• Grid analyses: one job for each tile.
• Facades: one job for each building batch.
• Daylight factor: one job for each part. Count the parts with client.analyses.preview_parts(request) (Python) or client.previewParts(request).
• Several analyses: each family has its own grid, so each has its own jobs. Solar-family analyses on the same grid and layers share the uploads. An upload saves time. It does not change the job count.

There is no result cache. The same run again is billed again. A repeat run with a geometryUrlStore skips the uploads. It still bills the jobs.

Count before you run

Use preview_area (previewArea). It sends no job.

1. Always give the analysis: analysis_type= (analysisType) or payload=. Without it, the Python preview uses the wind grid. A solar count is then about 4 times too high, and you get a warning. TypeScript requires analysisType.
2. Python: price from would_bill_jobs, not from tile_count. For facades, give payload=.
3. TypeScript: await previewArea(polygon, { analysisType }) counts tiles. This is right for a grid analysis. For facades, and to get the job count, use await previewAreaBatches(input, polygon, options). It reads plannedJobCount from the plan that runArea would send. Pass the same input and buildings as the run.
4. For facades, give the same packing as the run: "fast" can plan a different number of jobs than "regular".
5. One call prices one analysis. For three analyses, call it three times and add the results.
6. The price is the API's live price list (GET /billing/pricing at the API root), not a number in the SDK. The cost is the planned jobs times the price of one job of the analysis; the time is 10 s a job. Each client keeps the list for 20 minutes. pricing_source (pricingSource) is live, cached or stale: stale is an older list, used only because a new fetch failed. With no list and a failed fetch, the preview raises PricingUnavailableError.