Tutorial¶
Getting Started¶
To start using EveryPoint, create an account, and after entering your payment info, you'll receive your API keys which will allow you to start uploading imagery and creating jobs for processing. To help you get up and running quickly, refer to the tutorial below, which covers the main concepts of the API and provides you with sample code for a variety of use cases.
Your First API Request¶
In this example, you'll make your first API request to verify that both your account is working, and that you are able to communicate with the API.
Each request to the EveryPoint API must be authenticated with your account's key and secret, which are available on your API Keys page. Once you've created an account and are logged in, the code samples below will reflect your actual API keys.
As your first API request, perform a GET operation on the https://api.everypoint.io/v3/ URL:
If your authentication is working, you should receive the following JSON response:
For more details on making requests to the API, refer to the pages on the communication format or available endpoints.
Video to Point Cloud¶
In this example, you'll upload a video to the API, and process it to generate a point cloud. You can download the sample video for use in this tutorial, as well as download the expected output.
The full code listing is below, but refer to the following sections for a step-by-step overview of the process.
# Upload the video
# Returns video identifier: /videos/1111-1111
curl \
-u API_KEY:API_SECRET \
-F file=@path_to/video.mov \
https://api.everypoint.io/v3/instances/default/videos
# Create a job to generate the point cloud
# Returns job identifier: /jobs/2222-2222
curl \
-u API_KEY:API_SECRET \
-H "Content-Type: application/json" \
-d '{"function": "/functions/pixels-to-point-cloud",
"inputs": ["/videos/1111-1111"]}' \
https://api.everypoint.io/v3/instances/default/jobs
# Get the job's output
# Returns point cloud identifier: /point-clouds/3333-3333
curl \
-u API_KEY:API_SECRET \
https://api.everypoint.io/v3/instances/default/jobs/2222-2222
# Get the point cloud's details
# Returns download URL https://storage.everypoint.io/files?3333-3333
curl \
-u API_KEY:API_SECRET \
https://api.everypoint.io/v3/instances/default/point-clouds/3333-3333
# Download the point cloud
curl \
-L https://storage.everypoint.io/files?3333-3333 \
-o point-cloud.ply
:: Upload the video
:: Returns video identifier: /videos/1111-1111
curl ^
-u API_KEY:API_SECRET ^
-F file=@path_to\video.mov ^
https://api.everypoint.io/v3/instances/default/videos
:: Create a job to generate the point cloud
:: Returns job identifier: /jobs/2222-2222
curl ^
-u API_KEY:API_SECRET ^
-H "Content-Type: application/json" ^
-d ^"{\"function\": \"/functions/pixels-to-point-cloud\", ^
\"inputs\": [\"/videos/1111-1111\"]}^" ^
https://api.everypoint.io/v3/instances/default/jobs
:: Get the job's output
:: Returns point cloud identifier: /point-clouds/3333-3333
curl ^
-u API_KEY:API_SECRET ^
https://api.everypoint.io/v3/instances/default/jobs/2222-2222
:: Get the point cloud's details
:: Returns download URL https://storage.everypoint.io/files?3333-3333
curl ^
-u API_KEY:API_SECRET ^
https://api.everypoint.io/v3/instances/default/point-clouds/3333-3333
:: Download the point cloud
curl ^
-L https://storage.everypoint.io/files?3333-3333 ^
-o point-cloud.ply
import requests
# Upload the video
# Returns video identifier: /videos/1111-1111
response = requests.post(
"https://api.everypoint.io/v3/instances/default/videos",
files = {"file": ("video.mov", open("path_to/video.mov", "rb"))},
auth = ("API_KEY", "API_SECRET"))
print(response.json())
# Create a job to generate the point cloud
# Returns job identifier: /jobs/2222-2222
response = requests.post(
"https://api.everypoint.io/v3/instances/default/jobs",
json = {"function": "/functions/pixels-to-point-cloud",
"inputs": ["/videos/1111-1111"]},
auth = ("API_KEY", "API_SECRET"))
print(response.json())
# Get the job's output
# Returns point cloud identifier: /point-clouds/3333-3333
response = requests.get(
"https://api.everypoint.io/v3/instances/default/jobs/2222-2222",
auth = ("API_KEY", "API_SECRET"))
print(response.json())
# Get the point cloud's details
# Returns download URL https://storage.everypoint.io/files?3333-3333
response = requests.get(
"https://api.everypoint.io/v3/instances/default/point-clouds/3333-3333",
auth = ("API_KEY", "API_SECRET"))
print(response.json())
# Download the point cloud
response = requests.get(
"https://storage.everypoint.io/files?3333-3333",
allow_redirects=True)
with open("point-cloud.ply", "wb") as output_file:
output_file.write(response.content)
Upload a video¶
To upload a video, perform a POST request to the /videos endpoint.
This request may take a while to complete, as a response will only be provided once the file has been fully uploaded.
If the upload is successful, the JSON response should look like the following, where /videos/1111-1111 is the identifier of the newly uploaded video:
{
"success": true,
"data": {
"video": {
"uri": "/videos/1111-1111",
"name": "video",
"type": "mov",
"size": 28120249,
"created_by_job": null,
"url": "https://storage.everypoint.io/files?1111-1111",
"thumbnail_url": null,
"attributes": {},
"custom_attributes": {}
}
}
}
Create a job¶
Now that we have uploaded our video, we can create a job for processing.
This is accomplished by selecting an available function, listing the files that should be used as input, and creating the job in the API via a POST request to the /jobs endpoint.
In this example, because we want to create a point cloud, we'll use the /functions/pixels-to-point-cloud function, along with our uploaded video, /videos/1111-1111.
If successful, the JSON response will look like the following, where /jobs/2222-2222 refers to the newly created job:
{
"success": true,
"data": {
"job": {
"uri": "/jobs/2222-2222",
"status": "pending",
"priority": 0,
"inputs": ["/videos/1111-1111"],
"outputs": null,
"function": "/functions/pixels-to-point-cloud",
"settings": {},
"custom_attributes": {}
}
}
}
Retrieve the output¶
Once we've created a job for processing, we can query for its status to wait for it to be complete (for greater efficiency in knowing when a job is complete, refer to the webhook endpoint). Once a job is complete, it will contain a list of outputs that are the result of the processing operation. A job's status and outputs can be queried using a GET request to the job's URL.
If successful, the JSON response will look like the following, where the outputs have been set to /point-clouds/3333-3333:
{
"success": true,
"data": {
"job": {
"uri": "/jobs/2222-2222",
"status": "complete",
"priority": 0,
"inputs": ["/videos/1111-1111"],
"outputs": ["/point-clouds/3333-3333"],
"function": "/functions/pixels-to-point-cloud",
"settings": {},
"custom_attributes": {}
}
}
}
Download the point cloud¶
Now that we have an identifier for the output, we can query it to obtain a download URL. This is accomplished via a GET request to the file's URL:
A successful response will look like:
{
"success": true,
"data": {
"point_cloud": {
"uri": "/point-clouds/3333-3333"
"name": "point-cloud",
"type": "ply",
"size": 64625356,
"created_by_job": "/jobs/2222-2222",
"url": "https://storage.everypoint.io/files?3333-3333",
"thumbnail_url": null,
"attributes": {},
"custom_attributes": {}
}
}
}
From here, we can access the "url" value, and download the point-cloud.ply file for viewing.
If everything worked as expected, your output should be similar to the sample point cloud reconstruction.
Images to Mesh¶
In this example, you'll upload a set of images to the API, and have it process them to generate a textured mesh. The overall procedure is highly similar to the video to point cloud example. You can download the sample images for use in this tutorial, as well as download the expected output.
Upload images¶
To upload an image, perform a POST request to the /images endpoint.
This request may take a while to complete, as a response will only be provided once the file has been fully uploaded.
If the upload is successful, the JSON response should look like the following, where /images/1111-1111 is the identifier of the newly uploaded image:
{
"success": true,
"data": {
"image": {
"uri": "/images/1111-1111",
"name": "image1",
"type": "jpg",
"size": 7012039,
"created_by_job": null,
"url": "https://storage.everypoint.io/files?1111-1111",
"thumbnail_url": null,
"attributes": {},
"custom_attributes": {},
"annotations": []
}
}
}
Now, upload the remaining images in a similar manner, and record the identifiers of each of the newly added images (referred to as /images/1111-1111 through /images/9999-9999 in this example).
Create a job¶
Now that we have uploaded our images, we can create a job for processing.
In this example, we'll use the /functions/pixels-to-mesh function, along with our uploaded images, /images/1111-1111 - /images/9999-9999.
If successful, the JSON response will look like the following, where /jobs/aaaa-aaaa refers to the newly created job:
{
"success": true,
"data": {
"job": {
"uri": "/jobs/aaaa-aaaa",
"status": "pending",
"priority": 0,
"inputs": ["/images/1111-1111", ..., "/images/9999-9999"],
"outputs": null,
"function": "/functions/pixels-to-mesh",
"settings": {},
"custom_attributes": {}
}
}
}
Retrieve the output¶
Once the job is complete, it will contain a list of outputs that are the result of the processing operation. The job's status and outputs can be queried using a GET request to the job's URL.
If successful, the JSON response will look like the following, where the outputs have been set to /meshes/bbbb-bbbb:
{
"success": true,
"data": {
"job": {
"uri": "/jobs/aaaa-aaaa",
"status": "complete",
"priority": 0,
"inputs": ["/images/1111-1111", ..., "/images/9999-9999"],
"outputs": ["/meshes/bbbb-bbbb"],
"function": "/functions/pixels-to-mesh",
"settings": {},
"custom_attributes": {}
}
}
}
Download the mesh¶
Now that we have an identifier for the output, we can query it to obtain a download URL. This is accomplished via a GET request to the file's URL:
A successful response will look like:
{
"success": true,
"data": {
"mesh": {
"uri": "/meshes/bbbb-bbbb",
"name": "mesh",
"type": "zip",
"size": 27162218,
"created_by_job": "/jobs/aaaa-aaaa",
"url": "https://storage.everypoint.io/files?bbbb-bbbb",
"thumbnail_url": null,
"attributes": {},
"custom_attributes": {}
}
}
}
From here, we can access the "url" value, download the mesh.zip file, and extract it for viewing.
If everything worked as expected, your output should be similar to the sample mesh reconstruction.
Share Data¶
This example outlines the steps that are involved in sharing data with other EveryPoint users. This includes creating and sharing a folder of files, using shared custom attributes, and sending messages.
Create an instance¶
This step is optional, as you could use the default instance that is provided with your account. However, to mimic a new setup (where you might be creating a new application that should be logically separate from your other existing data), we'll create a new instance for this example.
We'll name our instance production, to mimic a setup where we have different instances for testing, development, and production.
To create the instance, we need to perform the following operation:
URL: https://api.everypoint.io/v3/instances
Method: POST
JSON request body:
The API will then respond with:
{
"success": true,
"data": {
"instance": {
"uri": "/instances/production",
"name": "production",
"description": "Instance used for production data."
}
}
}
We can now use the /instances/production URI in our following operations (or /instances/default if you chose to use the default instance).
Set the webhook¶
In order to be able to receive messages (and notifications that jobs have finished processing if we were to run a job) we need to set up a webhook for the instance. The webhook is a URL where JSON objects can be delivered that contain the details of the message or notification. Setting the webhook can be accomplished via the following operation:
URL: https://api.everypoint.io/v3/instances/production/webhook
Method: PATCH
JSON request body:
The API will then respond with:
Create a folder¶
In order to share files with other users, those files need to exist in a folder.
Therefore, let's create a folder named shared-files that we can eventually use to share the files.
To create a folder, we perform the following operation:
URL: https://api.everypoint.io/v3/instances/production/folders
Method: POST
JSON request body:
The API will then respond with:
{
"success": true,
"data": {
"folder": {
"uri": "/folders/shared-files",
"name": "shared-files",
"description": "Folder used for sharing files."
}
}
}
Create a custom attribute¶
In addition to sharing files, we can also share custom attributes that have been associated with those files.
This way, when another user accesses the shared files, they will be able to see the custom attribute values that have been assigned to the files (as otherwise they are hidden by default when viewed by another user).
Let's create a custom attribute named dataset_id that will be used to uniquely identify sets of images.
To create a custom attribute, we perform the following operation:
URL: https://api.everypoint.io/v3/instances/production/custom-attributes
Method: POST
JSON request body:
The API will then respond with:
{
"success": true,
"data": {
"custom_attribute": {
"uri": "/custom-attributes/dataset_id",
"name": "dataset_id",
"description": "Dataset ID.",
"shared": true
}
}
}
Upload files¶
Now that we've created our instance, folder, and custom attribute, we can upload files that we'll want to share.
Let's suppose we're uploading a file named image0001.jpg which was taken at 2pm on January 31, 2022, and we want to set the dataset_id value to 12345.
For this example, we'll upload the image to the folder directly (though there are several ways that files can be added to folders).
To upload the image, we perform the following operation:
URL: https://api.everypoint.io/v3/instances/production/folders/shared-files/images
Method: POST
Encoding: multipart/form-data
At the minimum, in order to upload the file, we need to include a form parameter named file that contains the name and contents of our sample image, image0001.jpg (refer to the tutorial code on uploading images for more details).
However, let's also include the values for the attributes as additional JSON-encoded form parameters (though these could be set afterwards if necessary):
{
"attributes": {
"date_time_local": "2022-01-31T14:00:00"
},
"custom_attributes": {
"dataset_id": "12345"
}
}
After the upload completes, the API will then respond with something similar to:
{
"success": true,
"data": {
"image": {
"uri": "/images/0123-4567",
"name": "image0001",
"type": "jpg",
"size": 1023456,
"created_by_job": null,
"url": "https://storage.everypoint.io/files?0123-4567",
"thumbnail_url": null,
"attributes": {
"date_time_local": "2022-01-31T14:00:00"
},
"custom_attributes": {
"dataset_id": "12345"
},
"annotations": []
}
}
}
At this point, additional files could be uploaded into the folder as necessary.
Share a folder¶
Once the files that we'd like to share have been added to the folder, we will now share that folder with another user. To accomplish this, we need to create a share for the folder using the following operation:
URL: https://api.everypoint.io/v3/instances/production/folders/shared-files/shares
Method: POST
JSON request body:
The API will then respond with something similar to:
{
"success": true,
"data": {
"share": {
"uri": "/folders/shared-files/shares/1234-5678",
"name": "Shared folder with user ABC.",
"share_id": "2345-6789",
"password": "abcd-efgh"
}
}
}
Now, we need to send the share_id and password values to the user with which we'd like to share the data.
Once the user has received those values, they can then connect to the share and create a read-only folder within their own instance that contains the shared files.
As a note, we can always add or remove additional files in the folder, and the receiving user will immediately see the changes. Additionally, a share can only be used once. So, to share a folder with multiple users, a new share will need to be created and sent to each user.
Send a message¶
Once another user has connected to the shared folder, it may be useful to send and receive messages.
For example, suppose an additional set of images was added to the shared folder using a new dataset_id.
It could be useful to transmit that new dataset_id to the other user so that they know to look for those new images.
To send a message to another user, we need to use the folder that is shared between us.
For example, to send the text "dataset_id: 12345", we leverage the following operation:
URL: https://api.everypoint.io/v3/instances/production/folders/shared-files/send-message
Method: POST
JSON request body:
The API will then respond with:
The receiving user will then receive a webhook call with the contents of the message.
Automatic Object Detection¶
This example outlines the steps that are involved to automatically detect objects within images. This includes setting up a trigger, receiving webhook notifications, and inspecting annotations.
Create an instance¶
This step is optional, as you could use the default instance that is provided with your account. However, to mimic a new setup (where you might be creating a new application that should be logically separate from your other existing data), we'll create a new instance for this example.
We'll name our instance quarry-south, to mimic a setup where we have different instances for separate physical locations where imagery is captured (in this case, a quarry where rock, gravel, and sand is mined, produced, and stored).
To create the instance, we need to perform the following operation:
URL: https://api.everypoint.io/v3/instances
Method: POST
JSON request body:
The API will then respond with:
{
"success": true,
"data": {
"instance": {
"uri": "/instances/quarry-south",
"name": "quarry-south",
"description": "Instance used for Quarry-South data."
}
}
}
We can now use the /instances/quarry-south URI in our following operations (or /instances/default if you chose to use the default instance).
Set the webhook¶
In order to be able to receive notifications that new objects have been detected we need to set up a webhook for the instance. The webhook is a URL where JSON objects can be delivered that contain the details of the notification. Setting the webhook can be accomplished via the following operation:
URL: https://api.everypoint.io/v3/instances/quarry-south/webhook
Method: PATCH
JSON request body:
The API will then respond with:
Create a trigger¶
To configure the instance to automatically detect objects in new images, we need to create a trigger. Triggers automatically perform actions, and we'll select the detect-objects action. The result of this action is that any new detected object in an image will create a new annotation for that image, where the annotation will have a 2D bounding box and label from the list of supported labels. To create the trigger, we perform the following operation:
URL: https://api.everypoint.io/v3/instances/quarry-south/triggers
Method: POST
JSON request body:
The API will then respond with something similar to:
{
"success": true,
"data": {
"trigger": {
"uri": "/triggers/1111-1111",
"action": "/actions/detect-objects"
}
}
}
Inspect annotations¶
When a new object is detected in an image, you will receive a webhook notification similar to:
{
"annotation": "https://api.everypoint.io/v3/instances/quarry-south/images/2222-2222/annotations/3333-3333"
}
This notification contains the URL to the newly-created annotation. You can get the details of the annotation via:
URL: https://api.everypoint.io/v3/instances/quarry-south/images/2222-2222/annotations/3333-3333
Method: GET
The API will then respond with something similar to:
{
"success": true,
"data": {
"annotation": {
"uri": "/images/2222-2222/annotations/3333-3333",
"label": "/labels/truck",
"geometry": {
"type": "box",
"min": {"x": 100, "y": 200},
"max": {"x": 500, "y": 400}
}
}
}
}
You can then also edit this annotation, or create new ones for other objects in the image.
Helpful Resources¶
The following are various resources to help you as you develop and test your EveryPoint-powered application.
3D Viewers¶
To help you view your 3D results, the following is a list of free tools that you can download and run on your computer:
- MeshLab - view point clouds (PLY files) or meshes (OBJ files), provides lots of options to manipulate meshes
- CloudCompare - view point clouds (PLY and E57 files) or meshes (OBJ files), provides lots of options to manipulate point clouds
Guides¶
For answers to common questions, refer to the FAQ.