Receptors

Echo supports two types of receptors, which are distinguished by how they are defined during their creation:

• Grids: rectangular shaped, grids are defined by its geometry and by the amount of receptor points in each direction
• Point Lists: sequences of receptor points that cover a certain geographical area, but with no particular shape

In this page, some sections include specific instructions on how to handle grids and point lists separately. Other sections include common instructions that are valid for both types of receptors.

Create a receptor grid

Interacting with the API

The endpoint below is used to create a receptor grid for project with ID project_id.

The payload that will be detected as a receptor grid includes the following elements:

Below is an example of how you can create a receptor grid for your project.

import requests

def create_grid(base_url: str, project_id: int, headers: dict):

    # Define payload for a square grid with evenly spaced receptors
    grid_payload = {
      "name": "My New Grid", 
      "x0": "0", 
      "y0": "0",
      "width": "50000", 
      "height": "50000",
      "x_count": "101", 
      "y_count": "101"
    }

    # Create grid
    grid_response = requests.post(
      f"{base_url}/p-{project_id}/receptors/",
      json=grid_payload,
      headers=headers
    )

    # Extract response after creating grid
    grid = grid_response.json()

Using the Website

Create a receptor point list

Interacting with the API

The endpoint below is used to create a receptor point list for project with ID project_id.

The payload that will be detected as a receptor points list includes the following elements:

Below is an example of how you can create a receptor point list for your project.

import requests

def create_point_list(base_url: str, project_id: int, headers: dict):

    # Define payload for a random sequence of points
    list_payload = {
      "name": "My New Point List", 
      "points": [
          {
              "x": 0,
              "y": 0,
              "z": 0
          },
          {
              "x": 2000,
              "y": 3000,
              "z": 500
          },
          {
              "x": 10000,
              "y": 10000,
              "z": 800
          }
      ]
    }

    # Create point list
    list_response = requests.post(
      f"{base_url}/p-{project_id}/receptors/",
      json=list_payload,
      headers=headers
    )

    # Extract response after creating point list
    point_list = list_response.json()

Using the Website

Upload a receptor point list file

Creating a JSON payload to create a list of receptor points, as it is described in Create a receptor point list, is useful for short lists, but it may become more complex if you wish to create a list with many points. For this reason, Echo allows you to upload a .csv file which is converted into a new receptor point list. This upload is done using the endpoint below.

Below is an example of how you can upload a file to create receptor point list.

from typing import Union
import requests
from pathlib import Path

def upload_point_list_file(base_url: str, project_id: int, headers: dict, file_path: Union[str, Path]):

    # Prepare file
    file = {"file": open(file_path, "rb")}

    # Upload file
    list_response = requests.post(
      f"{base_url}/p-{project_id}/receptors/upload/list/",
      files=file,
      headers=headers
    )

    # Extract response after uploading point list
    point_list = list_response.json()

Using the Website

Read a receptor

Interacting with the API

To read a single receptor with ID receptor_id from a project with ID project_id, the endpoint below can be used.

Besides the general information about a single receptor, this endpoint will also return the geographical points associated to that receptor. In the case of a point list, this is a trivial operation. For grids, Echo will first compute all the points based on the grid's parameters and then return them.

Below is an example of how you can read a single receptor.

import requests

def read_receptor(base_url: str, project_id: int, headers: dict, receptor_id: int):

    # Choose type of coordinates
    coordinate = "xy"

    # Read receptor
    receptor_response = requests.get(
      f"{base_url}/p-{project_id}/receptors/{receptor_id}/" + f"?coordinate_type={coordinate}",
      headers=headers
    )

    # Extract response after fetching receptor
    receptor = receptor_response.json()

Using the Website

Read all project receptors

Interacting with the API

It is also possible to obtain information about all receptors that are part of a project with ID project_id. To get this list, the endpoint below can be used.

Below is an example of how you can get a list with information about all receptors from a certain project. This response does not include information about the geographical points of each receptor.

import requests

def read_all_receptors(base_url: str, project_id: int, headers: dict):

    # Read all receptors
    receptors_response = requests.get(
      f"{base_url}/p-{project_id}/receptors/",
      headers=headers
    )

    # Extract response as a list after fetching all receptors
    receptors = receptors_response.json()

Using the Website

Update a receptor

Interacting with the API

Once a receptor is created, only its name can be updated. To make sure the finished calculations that use a certain receptor remain valid, Echo does not allow to change its definition / points.

To update a receptor with ID receptor_id in a project with ID project_id, the endpoint below is used.

The payload of this endpoint only includes the name field. To get more information about this field, check how to create a grid or how to create a point list.

Below is an example of how you can update a receptor's name.

import requests

def update_receptor(base_url: str, project_id: int, headers: dict, receptor_id: int):

    # Define payload
    update_payload = {
      "name": "My New Other Receptor",
    }


    # Update receptor
    receptor_response = requests.patch(
      f"{base_url}/p-{project_id}/receptors/{receptor_id}/",
      json=update_payload,
      headers=headers
    )

    # Extract response after updating receptor
    receptor = receptor_response.json()

Using the Website

Delete a receptor

Interacting with the API

It is possible to delete a single receptor with ID receptor_id belonging to a project with ID project_id. The endpoint below allows you to perform this action.

Below is an example of how you can delete a receptor.

import requests

def delete_receptor(base_url: str, project_id: int, headers: dict, receptor_id: str):

    # Delete receptor
    receptor_response = requests.delete(
      f"{base_url}/p-{project_id}/receptors/{receptor_id}/",
      headers=headers
    )

    # Extract information about deleted receptor
    receptor = receptor_response.json()

Using the Website