This tutorial demonstrates a reproducible workflow to isolate the thermal performance contribution of individual ground surface materials, benchmark a base case against systematically varied material assignments, and compare results across two climate scenarios — present-day and projected — using infrared.city Grasshopper connector.

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

• Starting a project: If you’re unfamiliar with the basics, check out the Running Your First Simulation Guide which walks through the setup and launch of environmental simulations step by step.

• Using the Grasshopper plugin: To get comfortable with the connector workflow, see Getting started with Connectors: infrared.city in Grasshopper where the process of linking simulations directly in Grasshopper is introduced.

What you will get

• A base case simulation reflecting existing ground surface conditions, providing the thermal comfort reference against which material interventions are evaluated
• A structured material substitution protocol — from uniform single-material assignments to composite surface configurations — enabling isolated assessment of each material type’s UTCI contribution
• A vegetation integration workflow for point-based tree placement with configurable species, crown diameter, and height parameters
• A parallel project structure connecting a current-condition EPW dataset and a projected future EPW to the same Grasshopper canvas, enabling direct scenario comparison
• Export-ready UTCI output layers — mesh geometry, simulation data, color maps, and KPI summaries — with threshold-adjustable visualization and area statistics

Step-by-step workflow

1) Initiate the project on the web platform

Projects must be initialized through the infrared.city web application before any Grasshopper operations can begin. Navigate to Create New Project, enter the target location, and confirm. The platform will automatically retrieve the closest available EPW file from TMY datasets for that geographic location. Thermal comfort analyses and any other simulation types can be configured either directly in the web app at this stage or later through the Grasshopper connector.

2) Configure the future climate scenario

To enable present-versus-future comparison, a second project must be set up with a projected weather file. In the first project’s Project Settings, locate the Closest Weather File section and select Edit. Upload the projected EPW file corresponding to your target future scenario. Click Clone Project to produce a duplicate that inherits all building geometries and analysis configurations from the original but references the projected climate dataset.

Rename both projects clearly in Project Settings — for instance, distinguishing current conditions from future projection — to ensure unambiguous identification when loading them in Grasshopper.

3) Open the shared Grasshopper canvas

Open the provided Grasshopper file. The canvas is organized into two parallel tracks: the left side connects to the current-conditions project; the right side connects to the future-projection project. Both tracks share the same component logic and can be operated independently or in tandem for direct comparison.

4) Authenticate and sync your workspace

Authenticate using the Login component and authenticate with your infrared.city credentials. Once logged in, this tab can be closed. To sync your account’s projects, delete the existing Projects dropdown, a new one linked to your account will appear automatically.

5) Load the project and access its components

Select your current-conditions project from the dropdown and connect it to Load Project. This imports project metadata, analysis configurations, and all associated geometries into the Grasshopper canvas. Upon loading, the connector automatically generates the following components:

• Buildings — editable building geometries as currently saved in the project
• Analyses — all analysis configurations set up in infrared.city webapp
• Ground Materials — the surface material layer as assigned in the project
• Vegetation — tree objects, if fetched during project initialization

These outputs are structurally independent from the Load Project block to prevent dependency conflicts. Use the Explode Project component to access individual project layers — buildings, analyses, site boundary, and ground surfaces — as distinct, addressable objects for downstream processing.

6) Add a Thermal Comfort analysis

Connect a Thermal Comfort Index analysis component to the Analyses input of the Update Project block. UTCI provides the primary metric for evaluating material performance in this workflow. Analysis configurations can be added or adjusted either through the web app prior to syncing, or directly in Grasshopper using the dedicated analysis components.

If new building geometry is to be introduced — for example, a design proposal — triangulate it first and connect it to the Geometry input of Update Project. This ensures the geometry is incorporated into all subsequent simulation runs.

7) Run the base case

With the Thermal Comfort analysis connected and ground and vegetation inputs left unconnected, click Update Project and trigger Simulate. This run represents the base case — the existing site condition with ground materials as-defined in the original project data. The output establishes the thermal comfort reference from which all material interventions are evaluated.

Material substitution experiments

8) Deconstruct the existing ground material layer

Connect the Ground output from Explode Project to the Deconstruct Ground Materials component. This separates the site’s ground layer into five distinct surface types — asphalt, concrete, soil, vegetation, and water — each exposed as an independent geometry (toggleable between mesh and brep via right-click on the component). These surfaces can now be individually routed, replaced, or combined in any configuration.

9) Experiment 1 — single material assignment

To evaluate the thermal effect of a single material type applied uniformly across the entire site, connect one surface output (e.g., asphalt) to a new Construct Ground Materials component and pass its output to the Ground input of Update Project. The component notes beneath Update Project confirm what the model contains — building count, analysis count, vegetation count, and ground surface count.

Run the simulation. The result isolates the UTCI response of that material as the exclusive ground cover, against which composite configurations in subsequent experiments can be compared.

10) Experiment 2 — composite material configuration

Reconnect the asphalt and concrete surfaces from the Deconstruct component as the existing surface geometry. To introduce a new surface type, draw a closed curve in Rhino delimiting the target area, set it as a curve parameter in Grasshopper, and convert it to a surface using the Boundary Surface component. Connect this output to a new Construct Ground Materials component, assign the desired material type (e.g., vegetation), and merge all surface outputs before passing them to Update Project.

Upon simulation, the model now reflects three distinct ground cover types. The resulting UTCI output quantifies the marginal thermal benefit of the introduced material zone relative to the base case.

11) Experiment 3 — plaza-scale intervention with trees

Draw closed curves in Rhino demarcating the intervention plaza. In Grasshopper, assign soil, vegetation surface, and water zones using Construct Ground Materials for the selected area. Connect the Ground output to Update Project.

To add trees, place point objects at the intended planting positions in Rhino and set them as a multi-point parameter in Grasshopper. Configure the Plant component by selecting species and specifying crown diameter and height. Connect the Plant output to the Vegetation input of Update Project and run the simulation. The results now reflect the combined UTCI effect of resurfacing and canopy introduction at the plaza scale.

12) Retrieve and visualize results

Connect the simulation output to the Results component. Four outputs are available: Mesh (georeferenced geometry), Data (raw UTCI values per cell), Colors (pre-mapped color representation), and KPIs (summary statistics). Use threshold sliders to define UTCI bands of interest and extract area share percentages for each defined range. This setup supports sensitivity testing and provides quantifiable outputs for design documentation and stakeholder reporting.

Examine future conditions and compare with today

13) Load the projected climate project

On the right side of the canvas, clear the Projects dropdown and reload the list. Select the cloned project configured with the projected EPW file. Load it and safely delete any newly generated geometry components (Buildings, Analyses, Ground Materials, Vegetation), these geometries are already accessible via the Explode Project component and do not need to be duplicated.

Repeat the same material configuration steps applied to the current-conditions track. With both tracks running equivalent material setups, UTCI outputs can be read side by side directly in the Rhino viewport, providing a spatially explicit comparison of present-day and projected thermal comfort conditions.

Why this helps

• Material performance is isolable — the deconstruct/construct protocol produces controlled single-variable experiments, making the thermal contribution of individual surface types empirically distinguishable.
• Future-proofing is built in — projecting forward with a modified EPW before any intervention is designed ensures that mitigation strategies are evaluated against the climate they will actually operate in, not the one they were designed in.
• Design guidance is quantified — the combination of material configuration experiments and UTCI threshold visualization translates directly into actionable targets: which surfaces to prioritize for replacement, where trees reduce exposure most, and by how much each intervention shifts area share within thermal stress bands.

Tips for robust results

• Use the component notes beneath Update Project to verify the model state before each simulation run — confirming building count, analysis count, and ground surface count prevents silent misconfigurations
• Store named snapshots of each material experiment to document the full sensitivity range across configurations
• When comparing current and future runs, use identical threshold values across both tracks to ensure UTCI band area statistics are directly comparable

What’s next

• Extend the material substitution experiments to test additional composite configurations — for example, progressive replacement of impervious surfaces with permeable or vegetated alternatives — to model incremental improvement trajectories
• Apply the parallel project structure to multi-city comparisons by initializing equivalent material configurations under different EPW datasets to examine how climate context modulates the thermal performance of identical interventions
• Combine ground material outputs with Sky View Factor and solar irradiation analyses to construct a multi-parameter site diagnosis that distinguishes between material-driven and morphology-driven thermal stress contributions