Vision Job API¶

Overview¶

The vision service is designed to be completely separable from other Authentise services. The only exception to this is that your model must be supplied to the model service so that the vision service and get snapshots of the model for comparison against real-world values

The first step is to configure cameras on the system

POST /config/
{
    node_uuid: "abc-123",
    priority: "speed",
    alerts: [{
        email: "test@authentise.com"
    }]
}
Location: /config/xyz-pdq/

We now have a configuration to alert the user at test@authentise.com whenever a print goes poorly. Next we’ll need a setup for one of the cameras. We get the camera location from the streaming client. Then

POST /camera/
{
    node_uuid: "abc-123"
    thresholds: {
        canny: 10,
        hough: 20,
        binary: 30
    },
    address: "0",
    printer: "https://print.authentise.com/printers/e4d-c4d",
    working_area: {
        start_x: 10,
        start_y: 15,
        width: 400,
        height: 300
    }
}
Location: /camera/aax-bbd/

This defines the camera “aax-bbd” which is the 0th camera on node “abc-123” and attached to printer “/printers/e4d-c4d”. Now that we have a full configuration we’re ready to do a print. We do that by creating a job

POST /job/
{
    node_uuid: "abc-123",
    camera: "https://vision.authentise.com/camera/aax-bbd/",
    model: "https://models.authentise.com/model/111-222-333/",
}
Location: /job/1234-abcde/

Now we have a job where we can collect image information and get alerts. As the print progresses we need to take a snapshot of each layer. We then get a location to upload that snapshot with

POST /job/1234-abcde/picture/
{
    layer_number: 12
}
Location: /job/1234-abcde/picture/0987-edcba/
X-Upload: https://some.upload.com/location/?signature=foobar

This indicates the desire to upload a picture of layer 12. After this request is made the picture should then be POST’d to the URL provided in X-Upload URL.

When the print is complete we simply update the job to indicate it

PUT /job/1234-abcde/
{
    status: 'complete'
}

Once the user PUTs this status no new pictures may be uploaded.

At any point during the job or after its completion the user may get access to the last picture that was taken with

Then access the resource for the picture.

Reference¶

This is the proposed API used for creating and performing vision operations for print jobs. It is not yet implemented.

POST /job/¶

This is how a vision job is created. The data required to start a new vision job is posted to this endpoint.

Request JSON Object:
	node_uuid (string) – Required. The UUID of the node being used for the print. camera (string) – Required. The URI of the camera being used for the print. Should be something like https://vision.authentise.com/camera/<uuid>/. model (string) – Required. The URI of the model being used for the print. For now this must be a model resource URI from our model warehousing service such as https://models.authentise.com/models/<uuid>/. layer_height (float) – Required. The layer_height, in mm, used to slice the model.
Response Headers:
	Location – The URI of this job where information about the job can be requested. Example /job/1234-abcde/

GET /job/<uuid>/¶

This contains information about the vision job.

Response JSON Object:

node_uuid (string) – The UUID of the node being used for the print. camera (string) – The URI of the camera being used for the print, such as https://vision.authentise.com/camera/<uuid>/. model (string) – The URI of the model being used for the print, such as https://models.authentise.com/models/<uuid>/. layer_height (float) – The layer_height, in mm, used to slice the model. status (string) – The status of the job. One of ‘in-progress’, ‘complete’ or ‘timed-out’. If a job is in-progress and no new picture requests are made over 24 hours then the job will be put in the ‘timed-out’ state. No new pictures can be uploaded unless the job is in the ‘in-progress’ state. last_picture (url) – Returns a URI that points to the last picture taken of this print.

POST /job/<uuid>/picture/¶

This url will generate an s3 url to which a picture for vision analysis can be uploaded for the given job. There will be one post to this, and one s3 url given out, per picture that needs to be analyzed. If the provided job is not in the ‘in-progress’ state then this endpoint will return 409. If the user attempts to POST multiple times to this endpoint with the same layer number then the POST will continue to return 201 without conflict. There are two possible types for a vision picture: ‘real’, a picture taken from a physical camera, and ‘simulated’, a picture generated from a rendering of an stl file.

Request JSON Object:
	layer_number (string) – Required. The current layer of the print. type (string) – Required. The type of the uploaded picture (either real or simulated).
Response Headers:
	Location – /job/<uuid>/picture/<uuid>/ X-Upload – The upload URL to which the picture needing anaylsis should be uploaded

GET /job/<uuid>/picture/¶

This gets the full list of pictures assosiated with the job_uuid.

Response JSON Object:
	pictures (list) – A list of pictures belonging to the vision job.
Response JSON Array of Objects:
	pictures[].uri (string) – A picture URI belonging to the vision job. The uri is of the pattern /job/<uuid>/picture/<uuid>/.

GET /job/<uuid>/picture/<uuid>/¶

This gets information about a picture that was taken for the job

Response JSON Object:

job (string) – The URI of the job this picture belongs to layer_number (string) – The layer of the print at which the picture was taken. type (string) – The type of the picture (either real or simulated). created (datetime) – The date and time when the picture upload url was created in ISO-formatted UTC content (url) – A URL where the content of the image can be downloaded if it was previously uploaded. This will be a signed URL that will expire after 20 minutes.

POST /job/<uuid>/correlation/¶

This posts a correlation value for the vision job. This is the correlation betweeen two pictures (real and simulated) for a given layer.

Request JSON Object:
	layer_number (int) – Required. The layer number at which the correlation was done. correlation_value (float) – Required. The correlation value obtained. version (string) – Required. The version of correlation used.
Response Headers:
	Location – The URI for this job where correlation information can be requested. Example /job/1234-abcde/correlation/5678-ghjkl/

GET /job/<uuid>/correlation/¶

This gets a list of correlation values for the vision job. This is a list of the correlations betweeen two pictures (real and simulated) each layer for which a correlation was posted.

Response JSON Array of Objects:
	layer_number (int) – The layer number at which the correlation was done. correlation_value (float) – The correlation value obtained. version (string) – The version of correlation used.

GET /job/<uuid>/correlation/<uuid>/¶

This gets a correlation value for the vision job by the correlation’s uuid. This is the correlation betweeen two pictures (real and simulated) for a layer.

Response JSON Object:
	layer_number (int) – The layer number at which the correlation was done. correlation_value (float) – The correlation value obtained. version (string) – The version of correlation used.

POST /config/¶

This is how vision config options are stored.

Request JSON Object:
	node_uuid (string) – Required. The UUID of the node being used for printing. priority (string) – Required. The print priority to use. This must either be speed or quality. alerts (list) – Required. This objects contains the alerts for updating the user. It can contain many phone_number and email objects, or none. An alert will be issued for each object in the list.
Request JSON Array of Objects:
	alerts[].phone_number (string) – This is a phone_number that will receive alerts. This lives inside the alerts list. alerts[].email (string) – This is an email that will receive alerts. This lives inside the alerts list.
Response Headers:
	Location – The URI of this config where information about the config can be requested. Example /config/1234-abcde

GET /config/¶

This is a way to get config information for a given node_uuid.

Query Parameters:
	node_uuid – Required. The UUID of the node for which the config information is being requested.
Response JSON Object:
	priority (string) – The print priority to use. This must either be speed or quality. alerts (list) – This objects contains the alerts for updating the user. It can contain many phone_number and email objects, or none. An alert will be issued for each object in the list.
Response JSON Array of Objects:
	alerts[].phone_number (string) – This is a phone_number that will receive alerts. This lives inside the alerts list. alerts[].email (string) – This is an email that will receive alerts. This lives inside the alerts list.

GET /config/<uuid>/¶

This is a way to get config information from the config uuid.

Response JSON Object:
	node_uuid (string) – The UUID of the node being used for printing. priority (string) – The print priority to use. This must either be speed or quality. alerts (list) – This objects contains the alerts for updating the user. It can contain many phone_number and email objects, or none. An alert will be issued for each object in the list.
Response JSON Array of Objects:
	alerts[].phone_number (string) – This is a phone_number that will receive alerts. This lives inside the alerts list. alerts[].email (string) – This is an email that will receive alerts. This lives inside the alerts list.

POST /camera/¶

This is how camera config options are stored.

Request JSON Object:
	node_uuid (string) – Required. The UUID of the node for which camera belongs. camera_address (string) – Required. The address in the computer at which the desired camera can be found. This probably will be an index value, but could possibly be a hardware device address. printer (string) – Required. The printer URI of the printer the camera is mounted on. thresholds (object) – Required. The object containing the different vision algorithm thresholds. thresholds.canny (integer) – Required. The threshold value for the canny filter. Must be an integer value 0-255 thresholds.hough (integer) – Required. The threshold value for the hough filter. Must be an integer value 0-255 thresholds.binary (integer) – Required. The threshold value for the binary threshold filter. Must be an integer value 0-255 working_area (object) – Required. The area defining the space in the camera view where the model will be printed. working_area.start_x (int) – Required. The x value of the top left corner of the working area. working_area.start_y (int) – Required. The y value of the top left corner of the working area. working_area.width (int) – Required. The width (length in x) of the working area. working_area.hight (int) – Required. The hight (length in y) of the working area.
Response Headers:
	Location – The URI where information about the camera can be requested. Example /camera/1234-abcde

GET /camera/¶

This returns a list of camera information for all cameras assosiated with the node.

Query Parameters:
	node_uuid – Required. The UUID of the node for which camera information is being requested.
Response JSON Array of Objects:
	camera_address (string) – The address in the computer at which the desired camera can be found. This probably will be an index value, but could possibly be a hardware device address. printer (string) – The printer URI of the printer the camera is mounted on. thresholds (object) – The object containing the different vision algorithm thresholds. thresholds.canny (integer) – The threshold value for the canny filter. Must be an integer value 0-255 thresholds.hough (integer) – The threshold value for the hough filter. Must be an integer value 0-255 thresholds.binary (integer) – The threshold value for the binary threshold filter. Must be an integer value 0-255 working_area (object) – The area defining the space in the camera view where the model will be printed. working_area.start_x (int) – The x value of the top left corner of the working area. working_area.start_y (int) – The y value of the top left corner of the working area. working_area.width (int) – The width (length in x) of the working area. working_area.hight (int) – The hight (length in y) of the working area.

GET /camera/<uuid>/¶

This contains information about the camera.

Response JSON Object:

URI (URI) – The URI of this camera. This will be the URL requested. Mostly useful when getting lists of resources. node_uuid (string) – The UUID of the node for which camera belongs. camera_address (string) – The address in the computer at which the desired camera can be found. This probably will be an index value, but could possibly be a hardware device address. printer (string) – The printer URI of the printer the camera is mounted on. thresholds (object) – The object containing the different vision algorithm thresholds. thresholds.canny (integer) – The threshold value for the canny filter. Must be an integer value 0-255 thresholds.hough (integer) – The threshold value for the hough filter. Must be an integer value 0-255 thresholds.binary (integer) – The threshold value for the binary threshold filter. Must be an integer value 0-255 working_area (object) – The area defining the space in the camera view where the model will be printed. working_area.start_x (int) – The x value of the top left corner of the working area. working_area.start_y (int) – The y value of the top left corner of the working area. working_area.width (int) – The width (length in x) of the working area. working_area.hight (int) – The hight (length in y) of the working area.

DELETE /camera/<uuid>/¶

This will remove a configured camera from the list of cameras on the node.

POST /camera/<uuid>/snapshot/¶

This is the location to upload a camera snapshot for config use.

Form Parameters:
	files – Required. The snapshot image file being uploaded.

GET /camera/<uuid>/snapshot/¶

This will get the camera snapshot previously uploaded.

GET /camera/<uuid>/snapshot/preview/canny/¶

This will get a preview of snapshot with the canny thresholding using the given parameters.

Query Parameters:
	threshold – Required. The threshold value for the canny filter. Must be an integer value 0-255

GET /camera/<uuid>/snapshot/preview/hough/¶

This will get a preview of snapshot with the hough thresholding using the given parameters.

Query Parameters:
	threshold – Required. The threshold value for the hough filter. Must be an integer value 0-255

GET /camera/<uuid>/snapshot/preview/binary/¶

This will get a preview of snapshot with the binary thresholding using the given parameters.

Query Parameters:
	threshold – Required. The threshold value for the threshold filter. Must be an integer value 0-255