The Full infrared SDK, Inside Your Parametric Workflow

The infrared.city Grasshopper workflow brings the full SDK into a parametric environment. Every analysis type the SDK supports (wind, solar and thermal models) runs directly inside Grasshopper. Change a parameter, re-run, and the results update in place. The geometry, the simulation, and the post-processing all live in the same file.

Large areas covered in a single run, with automatic tile stitching
8 analysis types: wind, thermal and solar models
Under 60 seconds typical result time for a district-scale UTCI run

You can download the ready-to-use Grasshopper file by filling out the form and work through the tutorial alongside the canvas.

Get the Grasshopper file

Fill in a short form to download it. The form loads from HubSpot, which may set cookies.


Area coverage at city scale

One of the constraints of running simulations in design tools has been area. Most plug-ins handle a building or a small site. This workflow handles districts.

The SDK tiles large analysis areas automatically. A 5 km² study area runs as a grid of tiles that are processed and stitched into a single result mesh. No manual splitting is required. If you need to go further, you can tile multiple workflow instances side by side and combine the outputs in Grasshopper. The tiling logic is handled by the SDK; your canvas just sees one result.

This makes the workflow useful not just for individual building studies, but for masterplan work, urban regeneration schemes, and comparative area analyses where you need to understand conditions across a whole neighbourhood at once.

Every analysis type, one workflow

The same core setup (IR Core, IR_ApiKey, IR_BYO, IR_Geometry, IR_Run) works across all SDK analysis types. Pick a different analysis from the value list and re-run. The geometry, location, and weather settings carry over.

AnalysisWhat it shows
Thermal Comfort (UTCI)Outdoor comfort at pedestrian height, in °C. Identifies heat stress zones and the effect of shade and planting.
Thermal Comfort StatisticsPercentage of hours in each stress category over a season or year. Useful for planning and policy reporting.
Wind SpeedMean wind speed at pedestrian height across the study area. Identifies uncomfortable or dangerous wind zones.
Pedestrian Wind ComfortLawson Criteria categories mapped spatially. Flags areas unsuitable for sitting, standing, or walking.
Solar RadiationCumulative solar energy on surfaces. Relevant for PV yield, overheating risk, and outdoor space quality.
Direct Sun HoursHours of direct sun at ground or surface level during a defined period. Standard input for many planning requirements.
Daylight AvailabilityDaylight factor at street level. Used in residential and public space quality assessments.
Sky View FactorThe fraction of sky visible from the ground plane. An indicator of urban density and nighttime cooling potential.

Solar radiation, direct sun hours, daylight and sky view factor can also run on facades and roofs, not just the ground. Pick the (facades) variant of the analysis to get values on every building surface.

What's on the canvas

When you open the GH file, numbered groups label everything you need to configure, in the order you use them. There are no hidden settings: the canvas is the documentation.

1. Load IR Core (once per machine)

IR Core carries the whole infrared.city library. It installs the Infrared SDK and loads it for every other component.

  • Toggle IR Core's install input to True.
  • Wait until its core output reads IR Core ready. The first run downloads the SDK and its dependencies, so give it up to a minute.
  • Restart Rhino if it asks you to.

The core output is already wired into every IR component that needs it. That wire makes Grasshopper solve IR Core first, so the library is loaded before anything else runs.

2. Set Your API Key

Flip the set_key toggle on IR_ApiKey to True. A dialog appears: paste your API key and confirm. The key is stored between sessions, so you only do this once. To enter a different key, flip reset to True. You can find your API key in the infrared.city web app under Billing → API Keys.

3. Bring Your Own Geometry (optional)

Everything here is optional. Connect what you have, leave the rest empty.

  • Buildings: Wire any mesh or brep geometry into byo_buildings: modelled in Rhino, generated parametrically, or imported. The component triangulates it automatically.
  • Trees: Wire Point3d objects at tree locations into trees. Set the canopy with byo_tree_radius and byo_tree_height, and pick a tree species from the value list (for example English oak, holm oak or stone pine).
  • Ground materials: Five curve inputs: asphalt, concrete, vegetation, soil, water. Wire closed curves from anywhere in your workflow. Leave any input empty if that surface doesn't appear in your design.
  • Terrain: Wire a terrain mesh into terrain if your site isn't flat.
  • Mix your own data with the SDK's. Set fetch_sdk_trees or fetch_sdk_ground to True to pull the SDK's context data and merge your own geometry on top. Keep them False to work with just the data you provide.
  • EPW weather file: Wire a file path to a local .epw file into byo_epw, using a Panel or a File Path component.

NOTE: Set the geometry inputs to List Access. The buildings, trees and ground material inputs each take multiple items. Right-click each of these inputs on IR_BYO → Access → List. With Item Access, the component runs once per item instead of once with the full set.

3B. Import From the Platform (optional)

Already set up a site on the infrared.city platform? IR_Import reads a platform export (.zip) so you can continue in Grasshopper instead of rebuilding the site.

  • Wire the file into path and pick a scenario from the list.
  • IR_Import returns the scenario's buildings, trees (with heights, radii and species), ground materials, site boundary, latitude and longitude, and weather file.
  • Wire these into step 3 (BYO) and step 4 (location). If the export holds analysis results, IR_Import can also return them as a result mesh with its legend values.

4. Site Location, Then Run the Geometry

Set lat, lon and radius_m on IR_Geometry, then set run to True. The radius defines how far from your centre point the SDK fetches context buildings, vegetation, ground materials and terrain.

NOTE: Radius is only needed when you bring no geometry of your own. If you wire in buildings, trees or ground materials in step 3, the simulation uses the extent of that geometry as the study area.

5. Visualize the Fetched Data

Before running a simulation, preview what the SDK has loaded for your area. Buildings appear as meshes in the Rhino viewport; trees appear as schematic trunk-and-crown forms. Your own geometry shows in the same preview, so you can check it sits where you expect. No tokens are used during preview.

6. Preview the Token Cost, Then Run the Analysis

Pick the analysis on IR_Run from three value lists:

  • analysis: for example utci (ground), wind (ground) or solar (facades). The facade variants exist for solar, sun hours, daylight and sky view factor.
  • months: a single month such as jul, a season such as jun-aug, or the whole year 1-12.
  • hours: for example 9-17 or 0-23.

Months and hours are ignored by sky view factor and wind. Optional overrides (wind speed and direction, wind comfort criteria, legend range, facade grid size) go into the settings panel.

preview_only = True shows the tiles and the token cost without running the simulation. Check this before a large run. Then set preview_only to False and switch run from off to on to start the simulation.

Ground results arrive as a coloured mesh on result_mesh. Facade results are drawn as textures on the buildings: switch the Rhino viewport to Rendered mode to see them, and set bake to True to keep them in the Rhino file.

7. Legend of the Results

IR_Legend draws a colour legend with values next to the result, using the range and palette of the run. Change steps or title to adjust it.

8. Post-Processing: Query Stats and Filter Results

IR_Query answers questions about a result. Wire IR_Run's result output into its results input, then set where:

  • Empty, with group_by set to building: one row per building with the mean, minimum, median and maximum value.
  • Points: the exact value at each point, and the building it hit.
  • Boxes, closed curves or a Rhino layer name: statistics inside each region.

Read the answers in the table output. IR_Filter keeps only the cells between min_val and max_val and tells you what share of the area that is.

9. Export to the Platform

IR_Export writes your Grasshopper geometry as files you can upload to the infrared.city platform under Data layers. That is useful to share a design with colleagues who work in the web app.

  • Set folder and name, then switch run on.
  • Buildings, trees, ground materials, the site boundary and the weather file are written as separate files. Choose GeoJSON or OBJ for buildings with buildings_format.
  • Upload each file on its row in Data layers. A GeoJSON file is placed on the map automatically; an OBJ file has no location, so you drag it into place.

Results that stay in Grasshopper

The analysis result comes back as a mesh with values per face. It stays in Grasshopper, which means you can post-process it parametrically: filter by value, query statistics per building or region with IR_Query, overlay with your geometry, export as CSV, or pipe directly into a custom visualization.

Compare two design scenarios by running the same location with different geometry wired in and differencing the result meshes. The parametric chain is unbroken from design model to simulation output.

The workflow file includes the complete Python 3 source for each component. If you want to extend it (add a new analysis type, change how results are displayed, wire outputs into your own post-processing logic), the code is there to modify. The SDK documentation covers every parameter the components expose.