Working with the Archilyse API — A Simple Example of Potential View

In our previous tutorial we looked at an example of running a DPOI simulation against an address.

Here, we’ll further explore the simulations provided by the Archilyse platform by running a Potential View simulation against an address.

About the Potential View

Potential View allows us to determine the maximum potential of the external view we can see from any point within a room.

To clarify, let’s take a step back…

Imagine an apartment and you are stood at the centre of it. You’re view of the outside is limited by the size of the windows and your relative position to them. More precisely — it’s limited by the walls.

As you move, your view of the outside world changes. Maybe you can see more of the river or maybe you can see more of a neighbouring building. This would describe the real view.

Now, imagine we removed all the walls; we have an uninterrupted view. This is the potential view.

Real View (left) vs. Potential View (right)

The above illustrates only a 2D field-of-view, however, we in fact measure the 3D field-of-view. The radius of our visual range is 50km. So, with potential view, we calculate everything you can see from the centre of a 100km wide sphere.

Steps

As before, here is a quick overview of the steps well take.

1. Get an API key
2. Create a building
3. Request a Potential View simulation for the building
4. Check on the status until complete
5. Fetch the results
6. Profit

Step 1: API key

Subscribe at Archilyse and create an API key. Once having a subscription you can invite multiple users each with their own API key.

Every call to the API must include the API key in the header.

Step 2: Create a building

Potential View simulations must run against an address. We therefore need to create a building that has an address stored on it.

We create a building by submitting a POST request to the /buildings endpoint. We need to make sure that we have included an address in the payload otherwise our potential view simulation cannot run.

Request:

curl -X POST \
  https://api.archilyse.com/v0.1/buildings/ \
  -H 'Authorization: APIKEY <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "address": {
    "city": "Zurich",
    "country": "Switzerland",
    "postal_code": "8008",
    "street": "Lindenstrasse",
    "street_nr": "32"
  },
  "description": "A building for Potential View demonstration",
  "name": "Potential View Demo Building"
}'

Response:

{
    "address": {
        "city": "Zurich",
        "country": "Switzerland",
        "postal_code": "8008",
        "street": "Lindenstrasse",
        "street_nr": "32"
    },
    "building_id": "5bb3596a7565d50009d25b20",
    "building_references": [
        {
            "id": "2684184.99#1245816.15#246.76",
            "source": "swiss_topo"
        }
    ],
    "created": "2018-10-02T11:41:30.897172Z",
    "description": "A building for Potential View demonstration",
    "height": 18.78,
    "name": "Potential View Demo Building",
    "number_of_floors": 6,
    "org_id": "development_organisation",
    "simulation_statuses": {
        "dpoi": {
            "created": null,
            "status": "not_requested",
            "updated": null
        },
        "potential_view": {
            "created": null,
            "status": "not_requested",
            "updated": null
        }
    },
    "site_id": "",
    "updated": "2018-10-02T11:41:30.897174Z",
    "user_id": "xoUNddmgPphwf8jOcsHR1nWkmWA2"
}

You may have noticed that the response object containers a number_of_floors value. This is important for us as we calculate the potential view on a floor-by-floor basis. Now we know that there are 6 we can calculate the potential view for any number of these. Actually, we can calculate the potential view for any floor number we want - real or not.

You’ll also notice that simulation_statuses.potential_view.status is currently "not_requested". Let's change that.

Step 3: Request a Potential View simulation for the building

Send a POST request to the /buildings/{building_id}/simulations endpoint specifying the simulation we want to run; in this case "potential_view".

We provide the floors for which we want to calculate the potential view as an array of integers.

Here, we are only requesting one floor — number 3. However, if we wanted all 6 of the floors, we’d request the following (note that these aren’t zero indexed).

"parameters": {  
    "floors": [1,2,3,4,5,6]  
}

Request:

curl -X POST \
  https://api.archilyse.com/v0.1/buildings/5bb3596a7565d50009d25b20/simulations \
  -H 'Authorization: APIKEY <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{  
   "simulation_packages": [  
     {  
       "name": "potential_view",  
       "parameters": {  
         "floors": [3]  
       }  
     }  
   ]  
 }'

Response:

{
    "building_id": "5bb3596a7565d50009d25b20",
    "simulation_transactions": {
        "potential_view": {
            "batch_id": "eqg6soo5yycija87cesw",
            "organization_id": "development_organisation",
            "status": "pending",
            "transaction_id": "qddo0gixy0hpgh7cnjhq"
        }
    },
    "status": "Pending"
}

Step 4: Check the status

To check on the status of the any simulation we make a GET request to the /buildings/{building_id}/simulations/status end point.

Request:

curl -X GET \
  https://api.archilyse.com/v0.1/buildings/5bb3596a7565d50009d25b20/simulations/status \
  -H 'Authorization: APIKEY <YOUR_API_KEY>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
​

Response:

{
    "dpoi": {
        "created": null,
        "status": "not_requested",
        "updated": null
    },
    "potential_view": {
        "created": "2018-10-02T11:47:06.992000Z",
        "status": "complete",
        "updated": "2018-10-02T11:47:06.992000Z"
    }
}

Step 5: Fetch the results

Now that the simulation is complete, we can fetch the results.

Request:

curl -X GET \
  https://api.archilyse.com/v0.1/buildings/5bb3596a7565d50009d25b20/simulations \
  -H 'Authorization: APIKEY <YOUR_API_KEY>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

Response:

{
    "potential_view": {
        "created": "2018-10-02T11:47:06.992000Z",
        "result": [
            {
                "absolute_height": 425.6,
                "category": "parks",
                "epsg": 2056,
                "heatmap": [...],
                "height": 10.65,
                "no_value_number": -666,
                "resolution": 1,
                "starting_point": [
                    2684172.903380449,
                    1245825.6244296706
                ],
                "summary": {
                    "average": 0.010031567976336208,
                    "max": 0.0162129234522581,
                    "median": 0.00919586792588234,
                    "min": 0.00652206223458052,
                    "std": 0.002439269901405811,
                    "strange": 0
                }
            },
            [...]
        ],
        "status": "complete",
        "updated": "2018-10-02T11:47:06.992000Z"
    }
}

Here, the result is an array of all the features we assess, namely ‘parks’, ‘trees’, ‘lakes’, ‘streets’, ‘mountains’, ‘buildings’, ‘rivers’, ‘railroads’, ‘grounds’, and ‘own_building’.

Step 6: Profit

Before we can make use of our results — let’s try to understand them. Here is section of the results corresponding to the ‘buildings’ category (i.e. how much of our filed of view is occupied by buildings).

{
    "absolute_height": 425.6,
    "category": "buildings",
    "epsg": 2056,
    "heatmap": [...],
    "height": 10.65,
    "no_value_number": -666,
    "resolution": 1,
    "starting_point": [
        2684172.903380449,
        1245825.6244296706
    ],
    "summary": {
        "average": 2.1598894336767365,
        "max": 7.81825590133667,
        "median": 1.85110878944397,
        "min": 1.45090234279633,
        "std": 1.0210781662748978,
        "strange": 0
    }
}

Working though, we’ll discuss some of the key features.

The absolute_height is the height above sea level while height is the height of the floor above ground level.

The real results lie within the heatmap. It contains a 2-dimensional array of values that represent the potential view at each point on the the floor plan. resolution specifies the size of the cells - in this case 1m. no_value_number is the value used to indicate a void. The values in the heatmap are measured in units of steradians.

This data allows us to construct a visual heatmap of the floor plan similar to what we see below.

There are two things I feel we should point out here. Firstly, we use a hexagonal mapping system in our heat maps — this allows for better fitting to complex boundaries. Secondly, we automatically determine the floor-plan for each level based on the building footprint — this is derived from a variety of sources.

The summary details the statistics for the heatmap data. So we can see what the average, minimum, and maximum values are for that floor.

Below is an example of how we have taken this heat-map data and imported it into Google Earth as a KML file. You can see how the values change when we cycle between the ‘street’ and ‘building’ potential view data.

Buildings and Street Potential View heat-maps in Google Earth

To read more about our API you can visit our interactive documentation.

If you have any questions or what to know more about how Archilyse can help you — just get in touch.