REST API - Send Images to PEKAT

Image processing through API works on the principle of sending the image via HTTP request and getting a response with the result (contains Context by default, but there are also other response types available). Only one image can be sent per request.

If you didn’t configure you project first check Project Configuration.

Request

PEKAT can handle two types of requests:

POST request - for analyzing images
GET request - for getting the last analyzed image and pinging the project

Both requests take an URL as an argument, that needs to be constructed from the target projects IP, port, requested command, response type and possibly some additional arguments.

The POST and GET requests and their different uses will be explained later on this page, but first we’ll focus on how to find out the IP address and port number of the target project.

Example of a request

import requests

url = f"http://{ip}:{port}/{command}&{required_arguments}&{optional_arguments}"

response = requests.post(
            url,
            data=image,
            headers={"Content-Type": "application/octet-stream"},
            timeout=timeout,
        )

Each request consists of at least:

URL that specifies where to send the request to the project and what is the project supposed to do
Timeout specifying how long to wait for response before aborting (for example, if the project isn’t running, the request would wait indefinitely)

Furthermore as you can see, the request can have additional arguments:

data - they are present only in case of the POST request. The data argument contains data of the image for processing
headers - in case that the request returns data as a result, the headers argument specifies the format of the data sent

URL

The URL for the requests would generally look like this:

url = f"http://{ip}:{port}/{command}"

But depending on the response type you may need to add arguments to the URL, in which case it would be modified to look like this:

url = f"http://{ip}:{port}/{command}?{argument1}={value1}&{argument2}={value2}&..."

In total, URL consists of:

IP address of the computer when the project is running
Port on which the project is running
Command that is telling the project what to do
required arguments - information that the project needs to perform the requested task
optional arguments - additional arguments that can be used to change the response type of the project as well as other things

IP address

The IP address that needs to be in the URL is the address of the machine on which the project is running. Alternatively, if the project is running on the same machine on from which you’ll be sending the requests, you can use address 127.0.0.1.

Port

The port in the URL is the port of the PEKAT project you want to connect to. The port can be found in Projects manager and it can be modified before starting the project.

Project port number

Once the project is running, both IP address and port are shown in the project window. The localhost is equivalent top IP “127.0.0.1“:

URL Command

Commands differ based on the used request. With POST request, the command specifies the format in which the image data is sent, whereas the commands with GET request can allow you to stop or ping the project or get the last analyzed image.

URL Arguments

URL arguments provide additional context to PEKAT, either required or optional and they differ based on the request and command.

Request Arguments

The arguments sent in the request are always

POST request

Post request is used to send images for analyzing to PEKAT project and get result. A general POST request to PEKAT project would look like this:

POST request commands

POST request has two different commands, depending on the type of data you’re sending for analyzing. Based on the command you also need to provide certain arguments and optional arguments. The two commands available to the POST requests are “analyze_image” and “analyze_raw_image”.

analyze_image

Is used for sending byte stream with data about .png image. This byte stream data also contain information about the width and height of the image, so it requires less arguments compared to the analyze_raw_image command.

It’s recommended to load the .png image data using the Path class from pathlib and simply use the .read_bytes() method like this:

The sent data must be of a .png file. The project won’t be able to process other formats.

The URL of this command doesn’t nee any other arguments, but it can be provided with some optional ones, that will be explained later.

Example of a code sending an image for analyzing using the analyze_image command:

analyze_image command is useful when you don’t want to preprocess the image, because it allows you to load and send images without the need to install and import any additional libraries.

analyze_raw_image

Is used for sending image as a raw numpy byte stream. This byte stream of a numpy array doesn’t contain information about the height and width of the image, so that has to be provided as additional required arguments in the URL.

You can load an image into a numpy image using the cv2 library like this:

After reading the image using cv2, you’ll have to find out it’s dimensions like this:

You also have to send the numpy array as byte stream which you can do like this:

Finally, if the image is in the Bayer RG format, you also need to specify this in the URL like this:

Example of a full analyze_raw_image request would look like this:

Additional optional arguments

The additional optional arguments that can be send in the URL of the request can be:

response_type - specifies the response type that is to be returned from the project, meaning what information it should contain
data - additional data to be send to project as a string that the project can use to separate the images in different flows and other things
context_in_body - the context of the analysis will be returned in the body of the response, meaning that the response will need to be parsed in a different way

Response type

Response type can be either:

context - the response will only contain context resulting from the analysis - this is the default response type
image - the response will contain processed image (without rectangles or heatmaps but with the changes from preprocess module)
annotated_image - the response will contain processed image with detected rectangles from all active modules
heatmap - response will contain layered heatmaps on the processed image

An example of a full POST request

Full analyze_raw_image POST request with all optional arguments would look like this:

The response returns byte data so to be able to use it in a meaningful way, you will first need to parse it into a usable data type.

GET request

Get request has 3 different types of commands and each is filling a different role. The commands available are:

ping - check if a project is running
stop - stop a project
last_image - get last analyzed image from a project

ping

This is a simple command that you can use to check whether the project is running or not. The URL of this command doesn’t take any additional arguments and it looks like this:

To check whether a server is running you can use this code:

stop

This is another simple command that can be used to stop a running PEKAT project, however it is recommended to use it only if you start PEKAT project as a process in your script. The code for this command would look like this:

last_image

You can use this command to get the last analyzed image from a running project. This can perhaps be useful when you’re sending images to a project from one script and then check the results in another one.

With this get request, you can also specify the response_type and you’ll also need to parse the result.

The request would look like this:

Parsing response from request

In case the request you sent is supposed to return some data in the response (as is the case for the POST request and with last_image command for GET request) you will have to parse the response from bytes to usable data. The parsing required varies somewhat based on the request response_type and whether you had set the “context_in_body” optional argument set.

The simplest option is when you had the response_type set to “context”, because you can just read the .json data from the response:

If you DON’T have “context_in_body” set in the URL, the image and the context will be sent in the separate parts of the response. Image in the content of the response and context in “ContextBase64utg” attribute of the response. If that attribute is None it means that no image was sent back and you can access the context just like when the response type is set to “context”.

If you DO have “context_in_body” set in the URL, the image and the context will be sent together and you’ll have to split them apart. You can do this by accessing the “ImageLen“ attribute of the response - it tells you how much of the data is the image (the first part) the rest is context. If ImageLen is None, no image was sent and again, you can just parse the context like when the response type is just “context”.

Finally, you can combine all of the options of parsing into one code if you want:

Testing the API functionality

If you have a running project on a port e.g. 8000, you can test the API by accessing this address in your browser (if PEKAT is running on the local computer, otherwise replace localhost with the IP address of the remote PC):

This displays the testing app, where you can choose to display the last processed image or send a new image to analyze. You can choose the Response type - Context, Image, Annotated image (image with a heatmap), or Heatmap. If the project has Secure image analyze enabled, you also need to enter the API key.

If Analyze image is chosen, you can also select the image that will be sent through the API. If the response type is different than the Context, the default behavior is that the image is sent in the body of the response and the context is sent in the headers - to change this and send both in the body, check the box with Context in the body. The detail of the request structure will be displayed.

After you click Send, you will also see the structure of the response in the blue info box, context (as you would see it in Inspection), and optionally an image based on the response type.

Knowledge Base 3.18