HowTo-Use.md

---

Content

1. How to use HIPE
   • JSON Requests
     • Syntax of a JSON request
     • Send requests to HIPE

---

[~] How to use HIPE

[..] JSON Requests

• Syntax of a JSON request
  • Usefulness of the request name
  • Processing chain and its filters
  • Scheduler
  • Linking data and supported data types
• Send requests to HIPE
  • Postman
    • Import requests
    • Create and edit a request
    • Save your request
    • Send a request
  • Web Interface
    
    
    
    
    
    

HIPE is a http server.
The communication method we use to transfer data is to send them using the JSON syntax.
If you never worked with it, you can quickly learn the basics by reading its documentation on the w3schools website

[..] Syntax of a JSON request

• Usefulness of the request name
• Processing chain and its filters
• Scheduler
• Linking data and supported data types
  
  
  
  
  
  

Here is a request as an example:

{
	"name": "resize",


	"filters": [
		{
			"RootFilter": { 
				"name": "root" 
			} 
		},
		{
			"Resize": {
				"name": "resize",
				"need": ["root"],
				"ratio": 4
			}
		},
		{
			"ShowImage": { 
				"name": "show",
				"need": ["resize"],
				"wait": 1
			}
		}
	],
	
	
	"orchestrator": "DefaultScheduler",
	
	
	"data": {
		"type": "IMGF",
		"path":"C:\\workspace\\data\\images\\image_01.jpg"
	}
}

The body of a valid JSON request contains:

• Its name (name field)
• The processing chain (filters array)
• The scheduler symbolizing how the chain's nodes will be processed (orchestrator filed)
• The data which will be processed by the chain (data field)

[..] Usefulness of the request name

The name is the most important information on a request. As your requests graphs will grow, building then processing them will take some time. One of the key concepts of HIPE is to capitalize and reuse the more possible things, even requests.
It is not currently possible to do so but in a future version you will be able to use a saved in database graph just by sending a JSON request containing its name, the desired scheduler, and the data to be processed. The filters array will not be needed anymore.

[..] Processing chain and its filters

The processing chain can be seen as a graph where each node is a different filter which will “do something” on its input data. So basically, a filter can represent an algorithm, like one which will alter an image, or another one which will find and identify an object in a video.

Let’s analyze in detail a filter extracted from the last example:

"Resize": {
	"name": "resize",
	"need": ["root"],
	"ratio": 4
}

Each JSON filter node must contain:

• A name, required for its identification (name field)
• A list of all its direct parents nodes’ names (need array)
• If existing, its exposed calibration parameters (in our case the ratio field)

In the JSON request body, the order on which all the filters are written is not important. You are not forced to do it in their logical processing order, the need arrays and name fields will be used by the chosen scheduler to reorder them.

As for the exposed calibration parameters, they are variables exposed in the source code. It permits us to fine tune their behavior without having to each time recompile the whole project again.

Note: In the case where the processing chain is saved in HIPE's database, you don't need to write the filters array part in your JSON request. The graph will be found using the request's name.

[..] Scheduler

As said before, the orchestrator is the scheduler which will reorder the processing of the nodes, taking into account their dependencies and the available hardware.
For now, only the DefaultScheduler model is available, where each filter will be processed sequentially respecting the dependencies order.

[..] Linking data and supported data types

[TODO]
HIPE can work with images, videos (or image sequences), as well as live data streams acquired from hardware like video cameras or RTP (Real-time Transport Protocol).

Here is a table containing the primary data types and their corresponding identifier tags

Type	Identifier	Note
image	IMGF	path: "image_path"
video	VIDF	path: "video_path"
webcam	VIDF	path: "id_cam" (i.e. 0,1, ...)"
image sequence	SEQIMGD	path: "images_dir_path"

To link some data to your request, you must add a data field. As shown in the example, the field is not part of the filters array.

The field must contain:

• The data type containing the identifier of the data type you want to use (type field)
• The data path (path field)

Note: Those data types can also be used as output. To stream the output we use GStreamer and the StreamResultFilter filter. More information will be added to the API documentation.

[..] Send requests to HIPE

The tool we use to edit and send JSON requests to HIPE is Postman. It is not a prerequisite, so you can alternatively use any tool you want.
Assuming you want to use Postman, you can download it here.
You will also find collections of tests requests in the /Hipe/tests/data/request/ folder. They are in the Postman format but it internally uses text, so you can open them in any text editor you want to peek at their content.

[..] Postman

• Import requests
• Create and edit a request
• Save your request
• Send a request
  
  
  
  
  
  

[..] Import requests

In Postman, every request must be part of a collection. To import a collection, you must simply click on the import button (1.) in the upper left corner of Postman’s interface. The collection will be shown in the left side bar. If the side bar is hidden you can show it by clicking on button Show/Hide Sidebar (2.) next to the import button.

[..] Create and edit a request

In Postman, all the opened requests are shown in different tabs. By default, if no request is already opened, a new one will be shown and it is possible to directly edit it. But, if at least one request is opened, the default empty one will be hidden and you will need to click on the plus sign button at the right of the last opened request’s tab to create a new one (3.).
To be able to write the request, you must chose the POST mode instead of the GET mode (4.). It will unlock the Body tab. It is here that you will write the content of the request. You will also have to check the raw button to enable text edit, then chose the JSON (application/json) instead of text in the orange drop down menu to enable syntax highlighting.

[..] Save your request

You can save your request by clicking on the Save button at the right of the request’s tab window (5.). Remember that in Postman, every request must be linked to a collection. If no collection was already created, you will have to create a new one. You can do so by clicking on the + Create Collection button at the bottom of the opened save dialog.

[..] Send a request

HIPE’s http server listen on port 9090.
When used in a debug environment, you will probably deploy the server locally. In that case, the address will be localhost. If deployed on a remote environment, you will have to input the corresponding IP address (6.).
A complete address will be similar to: localhost:9090/json.
To send the request you will have to click on the blue Send button (7.). The server will then send its response when the processing will be done. The response is also in JSON format and will be shown just below the body of the sent request.

Note: HIPE internally uses the 9090 port to listen for and send JSON requests but It will change in the near future with the apparition of configuration files. You will be able to manually set the port you want to use.

[..] Web Interface

An alternative to postman is our webapp call us for more precision.