Building KPI Workflows in Grasshopper with the infrared.city Plugin

Understanding how design interventions affect thermal comfort in the built environment is essential. Buildings, vegetation, and urban geometry all shape microclimate conditions, influencing how people actually experience outdoor spaces. Measuring these effects allows us to move beyond intuition and quantify whether a scenario truly improves comfort or not.

Thermal comfort analysis provides a way to assess how outdoor spaces feel—whether too hot or comfortably cool—by considering factors such as air temperature, radiation, humidity, and wind. These insights are crucial for shaping design decisions in dense urban areas, where heat stress directly affects walkability, public health, and overall quality of life.

This tutorial explains how to calculate and visualize two custom KPIs for thermal comfort index studies using the infrared.city Grasshopper plugin. The workflow builds on data exported from the web app and processes it into easy-to-read performance metrics.

You can download the ready-to-use Grasshopper file filling the form and start exploring alongside the blogpost.

The workflows and KPIs presented here are just one example of how you can post-process infrared.city simulation results. By extracting and analyzing the raw outputs in Grasshopper, you gain the flexibility to build custom metrics, visualize impacts in new ways, and adapt the process to your specific design goals. Whether it’s developing additional KPIs, integrating results into optimization routines, or linking them with other environmental datasets, the possibilities are open-ended. We encourage you to experiment with these methods and extend them further, creating your own tailored post-processing workflows that bring unique insights into your projects.

Step 1: Initiate Your Project on the Web App

Before moving into Grasshopper, every workflow begins on the infrared.city web app, where you set up your simulation project. This includes defining your site, selecting analysis parameters, and launching the initial run.

• 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.

In this case study, we initiated a project for Hong Kong, added a Thermal Comfort Index analysis, and set the parameters to August and noon hours to capture a typical hot summer condition.

• Running thermal comfort analysis: For those new to thermal comfort simulations, the Getting started: Thermal Comfort Simulations guide explains how to configure and run thermal comfort evaluations from start to finish.

Once your project is initiated, you can seamlessly connect it to Grasshopper for advanced post-processing and KPI analysis.

Step 2: Connecting Grasshopper with Your infrared.city Project

Before setting up KPIs, Grasshopper needs to be linked with your infrared.city project. This connection ensures that the analysis you run in the web app becomes accessible in your Grasshopper environment, where you can process the data further and build custom indicators.

• 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.

Login to infrared.city

Start by using the Login component. This authorizes your Grasshopper session with your infrared.city account. Once logged in, press Refresh to display all active projects linked to your account.

Select and load your project

After logging in and refreshing, the Active Projects List will display your available projects. To make a selection:

• Place the Load Project component on the canvas.
• Use the dropdown menu to pick the desired project from the list.
• Finally, click Load Project to import all related data into Grasshopper.

This will fetch all the simulation data and make them available inside Grasshopper.

Once the project is loaded, Grasshopper automatically adds three data components to your script:

• A Geometry component, which contains any editable geometry stored in your project, and
• An Analysis component, which includes the analysis setup and parameters from the web app.
• An Vegetation component, which includes the existing trees in your simulation area.

Because of Grasshopper’s history-based workflow, these components are not directly tied to the Load Project component. This separation ensures you can freely update or replace geometry without duplication. To keep your script organized, you can rename these components or bake and remove the geometry component once you no longer need it.

In most cases, the geometry imported with the project is treated as context geometry. You can safely bake it, make modifications, or completely replace it with your own site geometry.

Manage loaded data and prepare geometry

In this case study, we bake the context geometry (the surrounding buildings) and then connect it to the geometry input of the Upload component. To streamline this process, we use a Geometry Pipeline to automatically reference all meshes from the Rhino layer where the baked context geometry is stored. This way, any updates made in Rhino are instantly reflected in Grasshopper without the need for manual re-imports.

It’s important to note that the uploading process will be done twice:

1. First with the base case, the empty plot without the new design geometry.
2. Then with the design scenario, the tower added to the context.

By running both versions, we can later compare the simulation outputs directly and evaluate how the proposed tower changes thermal comfort across the site.

Update and run the simulation

After preparing your geometry and project setup, the next step is to update and run the simulation directly from Grasshopper:

1. Connect the context geometry and the Project ID to the Update Project component.
2. Link the Update Project output to the Simulate component.
3. Click Run in the Simulate component to start the simulation.

Once the run is completed, the results will appear in the output. At this stage, it’s important to flatten the data output. This ensures that all results are treated as a single list, avoiding issues with nested data structures when building KPIs later.

Connect simulation output to Basecase Data

After the simulation run is completed, the results can be linked into the workflow. To do this, connect the output of the Simulate component to the Basecase Data component.

This step stores the results of the base case simulation (the empty plot) and organizes the data so it can be used later for KPI calculations. The Basecase Data component essentially acts as a bridge, it captures the results and forwards them directly into the upcoming KPI workflows.

Define your site boundary

Before moving on to KPI calculations, it’s important to limit the analysis area to your actual site. By default, simulations run across the entire grid, which include surrounding streets or neighboring parcels.

You can specify the site boundary using the Explode component of infrared.city to extract the site outline directly from the simulation grid. To do this, you should first draw your project site in the web app when creating your project. If you did not define it earlier on the webapp, this can be also done in Rhino or Grasshopper, either with a fully parametric generation method, or by simply referencing manual geometry from Rhino into the relevant components.

Once the site border is defined, the KPIs will only evaluate results within your designated area, ensuring the metrics reflect the performance of your project rather than the entire simulation domain.

Internalize the Basecase Data

Once the Basecase Data component is connected to the results, you can internalize the data. To do this, right-click on the component and select Internalize Data.

This action disconnects the component from the live Results output but keeps all values stored inside the component itself. In other words, you now have a static record of the basecase results saved directly in your Grasshopper definition.

This step is necessary because the workflow must be repeated for the design scenario (with the tower added). By internalizing the basecase data before proceeding, you ensure that the results are preserved. Without internalization, the basecase output would be overwritten once the second simulation is executed.

Step 3: Add your design geometry

With the basecase results secured, the next step is to introduce your design geometry into the workflow. This geometry represents the intervention you want to test, in this case, the design scenario.

You can bring in the design geometry directly from Rhino using the Geometry Pipeline component to reference objects placed on a dedicated Rhino layer (e.g., Tower). Any updates made in Rhino will automatically be reflected in Grasshopper. If you are working in a parametric design workflow, you can generate the geometry directly in Grasshopper and connect it to the simulation components. This flexibility allows you to either reference an existing model or keep everything fully parametric, depending on your project setup.

Both the context geometry (e.g., surrounding buildings) and the new design geometry must be connected to the geometry input of the Upload Project component. This ensures that the simulation reflects the full site condition with the proposed intervention included.

Run the design scenario simulation

After uploading the project with both the context and design geometry connected, the simulation can be run again.

To do this, click Upload on the Upload Project component and then click Run on the Simulate component. Once the simulation has finished, use the flattened Data output from the Results component and connect it to the Design Scenario Data component. This step stores the results of the tower scenario, which can now be directly compared with the previously internalized basecase data for KPI calculations.

Step 4: Comparing Results with Custom KPIs

Once both the basecase (empty plot) and the design scenario (tower added) simulations are completed and stored in Grasshopper, we can start comparing them. To make this comparison meaningful, we use two custom KPIs that highlight different aspects of thermal comfort change.

KPI 1: “≥ 1 °C Change Area (%)”

This KPI measures how much of the site experiences a meaningful temperature shift when comparing the design scenario against the baseline. Specifically, it calculates the percentage of the area where the temperature difference is greater than or equal to a chosen threshold (by default, 1 °C).

Methodology:

• Per-cell temperature values from both the baseline and the design scenario are used as input datasets.
• A cell-by-cell subtraction is performed to calculate the absolute temperature difference at each grid location.
• A threshold criterion (e.g., ≥ 1 °C) is then applied to identify all cells where the difference meets or exceeds the specified magnitude of change.
• The number of qualifying cells is normalized by the total number of cells in the analysis domain, yielding the proportion of the site area that exhibits a temperature change greater than or equal to the defined threshold.

Why it matters:

Even a small temperature change can strongly affect outdoor comfort. This KPI helps us see whether a design intervention has a widespread impact across the site, or if its influence is limited to just a few zones.

• The output is a single number between 0–100%, representing the share of the site affected by at least the chosen temperature change.
• The threshold can also be adjusted (for example, ≥ 0.5 °C, ≥ 1 °C, ≥ 2 °C) to explore different levels of sensitivity.

For this case study in Hong Kong (August, noon conditions), the results highlight the effect of adding a tower to the site. KPI 1 (≥ 1 °C Change Area %) shows that around 69% of the site experiences at least a 1 °C difference compared to the basecase, meaning the intervention has a broad spatial impact.

KPI 2: “% Drop of Baseline Peak (by Average)”

While KPI 1 focuses on coverage, this KPI measures intensity. It looks at how much cooler the design scenario is compared to the hottest point in the baseline. In other words, it expresses the reduction in temperatures as a percentage of the baseline’s maximum value.

Methodology:

• The maximum temperature value within the baseline dataset is first identified to serve as the reference peak.
• For each grid cell in the design scenario, the relative reduction is calculated by comparing the scenario temperature to the baseline peak. In practice, this means subtracting the scenario temperature from the baseline maximum, dividing the result by the baseline maximum, and then multiplying by 100 to express it as a percentage.
• This operation yields a percentage reduction value for each grid cell, expressed relative to the baseline maximum temperature.
• The average of these per-cell reductions is then computed across the entire domain, producing a single scalar value that represents the mean percentage reduction of scenario temperatures relative to the baseline peak.

Why it matters:

• This KPI tells us how effective a design option is in reducing overall heat stress relative to the worst-case condition. It provides an intuitive way to understand how much of the peak heat is “shaved off” on average across the site.

For this case study in Hong Kong (August, noon conditions), KPI 2 (% drop of baseline peak) is 5.5%, indicating that while the tower influences a large share of the site, the average reduction relative to the hottest baseline condition is more modest.

Summary

• KPI 1 (≥ 1 °C Change Area %) answers: How much of the site is affected by meaningful temperature change?
• KPI 2 (% Drop of Baseline Peak by Average) answers: How effective is the design at lowering site-wide temperatures compared to the hottest baseline condition?

Together, these two KPIs provide both spatial coverage and intensity of effect, giving a balanced view of how design interventions influence thermal comfort.