Heatmap

The Butlr Heatmap API provides a powerful way to visualize occupancy patterns across physical spaces. This feature generates a grid-based representation of detection density, allowing you to identify high-traffic areas, understand space utilization patterns, and make data-driven decisions about space optimization.

Overview

The heatmap functionality maps normalized sensor coordinates to physical space with configurable grid resolution, providing an accurate representation of occupancy patterns. The API returns data in a structured format that represents occupancy grid cells, making it easy to visualize where people spend time in your spaces.

Key Features

1. Physical Space Mapping: Proper dimensions in meters with accurate spatial representation

2. Configurable Grid Resolution: Choose from 0.25m, 0.5m, or 1.0m grid sizes

3. Center-point Based Grid: Each cell is represented by its center point coordinates

4. Sparse Grid Representation: Only non-empty cells are returned by default

5. Optimized Performance: Efficient processing of large detection datasets

Important Note: There is currently a 7-day limit to the time range that can be queried in the heatmap API. For longer periods, you'll need to make multiple queries and combine the results.

---

Example Query

The following example demonstrates how to retrieve heatmap data for a floor using the Detections API.

POST https://api.butlr.io/v3/detections

// POST https://api.butlr.io/v3/detections
{
  "data_types": ["heatmap_v2"],
  "filter": {
    "space_id": "space_2qfeX6pnfGCeD4r49CtSJqYq456",
    "start": "2024-01-01T00:00:00Z",
    "stop": "2024-01-08T00:00:00Z",
    "omit_empty_value": true
  },
  "window": {
    "heatmap_v2_options": {
      "grid_resolution": 0.5,
      "heatmap_type": "occupancy",
      "normalize": false
    }
  }
}

---

Key Parameters

1. Data Types:

   • "data_types": ["heatmap_v2"]: Specifies that we want heatmap v2 data.

2. Filter Parameters:

   • "space_id": "space_XXXX": Filters the query to the specific floor (replace space_XXXX with the floor ID).

   • "start": "2024-01-01T00:00:00Z": The start time of the query period.

   • "stop": "2024-01-08T00:00:00Z": The end time of the query period (maximum 7 days from start).

   • "omit_empty_value": true: Whether to omit cells with zero detections in the response.

3. Window Parameters:

   • "grid_resolution": 0.5: Specifies the grid cell size in meters (0.25, 0.5, or 1.0).

   • "heatmap_type": "occupancy": The type of heatmap (currently only "occupancy" is supported).

   • "normalize": false: Whether to normalize values (0-1).

---

Response Format

The API returns data in a structured JSON format that represents the occupancy grid cells:

{
  "heatmap_v2": {
    "array_cells": [
      [14.75, 35.25, 64],  // [x, y, value] format
      [47.5, 13.5, 46332],
      [0.5, 19.5, 249],
      // Additional cells...
    ],
    "metadata": {
      "type": "occupancy",      // Type of heatmap
      "resolution": 0.5,        // Grid cell size in meters
      "total_detections": 18609968, // Total number of detections
      "max_value": 1410752,     // Maximum detection count in any cell
      "bounds": {
        "min_x": -6.5,
        "max_x": 57.5,
        "min_y": -3.5,
        "max_y": 35.5
      }
    }
  }
}

Each cell in the array_cells array contains:

• Position [0]: X-coordinate of the cell center (in meters)

• Position [1]: Y-coordinate of the cell center (in meters)

• Position [2]: Detection count/value for that cell

The metadata provides important context:

• bounds: Physical boundaries of the heatmap area (min/max coordinates)

• resolution: Size of each grid cell in meters

• max_value: Maximum detection count in any single cell

• total_detections: Sum of all detection counts across all cells

• type: The type of heatmap (currently only "occupancy" is supported)

---

Customizing Your Queries

• Grid Resolution: Adjust "grid_resolution": 0.5 to other values like 0.25 or 1.0 depending on the level of detail needed.

• Time Range: Modify "start" and "stop" to align with your analysis period. Longer time ranges will show cumulative patterns over time.

• Include Empty Cells: Set "omit_empty_value": false in the filter to include cells with zero detections in the response.

• Normalization: Set "normalize": true to normalize values between 0 and 1, which can be useful for visualization.

Performance Note: The heatmap API is optimized for efficient processing of large datasets. Performance is primarily determined by the number of detections processed rather than the time range queried.

Advanced Usage

Visualizing Heatmap Data

Heatmap data is typically visualized as a color gradient overlaid on a floor plan, with color intensity indicating the relative number of detections in each grid cell. Common visualization approaches include:

1. Color Gradient: Using a color scale from cool (low values) to warm (high values)

2. Opacity Mapping: Varying the opacity based on detection count

3. 3D Surface: Creating a 3D surface where height represents detection count

Note: The visualizations shown above require post-processing code to render the heatmap API data. The API returns the raw data points, which need to be processed and rendered using visualization libraries such as matplotlib in Python. The checkerboard visualization demonstrates that the API only returns cells that have at least one detection (shown in white), while empty cells (shown in black) are omitted by default.

Analyzing Occupancy Patterns

Heatmap data can provide valuable insights into space utilization:

• Identify High-Traffic Areas: Locate areas with the highest detection counts

• Discover Underutilized Spaces: Find areas with minimal activity

• Optimize Layout: Use occupancy patterns to inform space redesign

• Compare Time Periods: Analyze how space usage changes over different time periods

Combining with Other Metrics

For a comprehensive understanding of space utilization, combine heatmap data with other metrics:

• Room Occupancy: Compare heatmap patterns with room-level occupancy counts

• Traffic Data: Correlate movement patterns with entry/exit traffic

• Presence Time: Analyze how long people stay in different areas

Aggregating Data for Longer Time Periods

Due to the 7-day limit on heatmap queries, analyzing longer time periods requires multiple queries and aggregation:

1. Split the Time Range: Divide your analysis period into 7-day segments

2. Make Multiple Queries: Query each segment separately

3. Combine Results: Aggregate the cell values from each response

4. Normalize if Needed: Adjust values to account for different time periods

This approach allows you to analyze occupancy patterns over weeks, months, or even longer periods while respecting the API's time range limitations.

For real-time occupancy data, refer to the Real-time Occupancy documentation.