The SmartFace platform can generate a tcp stream with enhanced video preview for each stream from the camera. The stream is encoded in MPEG-1 format, and can be used in any third-party application, such as VMS.

Quality of encoded streams can be defined separately for each camera. If the stream is encoded, you can access it via defined port: tcp://<server_name>:<camera_preview_port> (e.g. tcp://localhost:30011/)

images/download/attachments/145949414/image2021-12-5_13-51-43.png

Use VLC player to preview the stream

Camera stream preview configuration

To enable stream preview and define the quality of the stream, use REST API endpoint: /api/v1/Cameras

Preview configuration in the camera definition:

{
	...
    "mpeG1PreviewEnabled": true, 	// "true" or "false"  
    "mpeG1PreviewPort": 30011,
    "mpeG1VideoBitrate": 1400000,
    "previewMaxDimension": 1280,
	...
}

Parameter	Description	Values
mpeG1PreviewEnabled	Enhanced camera stream preview enabling.	Set "true", to enable the preview.
mpeG1PreviewPort	TCP port where the stream will be available.	Default value is generated by the platform: 30000 + camera_number (e.g. for SFCam1 the preview port is set to 30001)
mpeG1VideoBitrate	Maximum bitrate for encoded preview stream. Lower value = lower quality.	Low quality: 153000 Medium quality: 450000 (default) High quality: 1400000
previewMaxDimension	Encoded preview stream resolution. Longer side of the input stream.	Low quality: 426px Medium quality: 640px (default) High quality: 1280px

Use enhanced camera stream preview wisely. MPEG-1 encoding is CPU power consuming feature, you need to take this to consideration during your SmartFace system design.

Preview port generation

When preview port is specified in the create/update camera request, then the enhanced preview will be available on this port.

When not specifying preview port in the create request, then API calculates the preview port based on Camera sequence number, starting at 30 001. That means that the first camera created will use preview port 30 001, the second will use 30 002 and so on. This mechanism is good for eliminating port collisions when SmartFace runs natively on a single host (e.g. Windows deployment).

When running in containerized workflow we don't need to handle port collisions, and on the other hand a more predictable assigning ports to camera entities is useful for configuring the infrastructure. API can be configured to use a static port when creating new cameras with CameraDefaults configuration in SmartFace.Api.appsettings.json :

"CameraDefaults": {
  "PreviewPort": null
},

Default value of PreviewPort is null and in this case, the API performs the Camera sequence calculation described above. When any other value is provided, then the provided value is used for newly created cameras.

The preview port can also be configured by setting value to env variable CameraDefaults__PreviewPort

Object bounding box color

In the SmartFace enhanced camera stream preview, different bounding boxes can appear:

detected face bounding box - default color is yellow (#ECEC5E)
identified person bounding box - default color is green (#4ADF62)
identified person from restricted watchlist bounding box - default color is red (#57514C)
detected pedestrian bounding box - default color is blue (#80B5FF)

To change default color for detected faces and pedestrians bounding boxes, use REST API endpoint: /api/v1/Setup/Preview

{ 
  "faceBoundingBoxColor": "#ecec5e",
  "pedestrianBoundingBoxColor": "#80b5ff" 
}

To change the default color value for an identified person from the watchlist, use REST API endpoint: /api/v1/Watchlist

Identified person bounding box color in watchlist definition:

    {
	  ...
      "previewColor": "#4adf62",
      ...
    }

Preview attributes

In addition to bounding boxes, the SmartFace Platform can display different object attributes on semitransparent placeholder. You can define separately, what attributes will be displayed for each camera stream preview.

images/download/attachments/145949414/full.png

To set the font size and each attribute visibility in the stream preview, use REST API endpoint: /api/v1/Cameras

Preview attributes visibility configuration in the camera definition (default values):

{
  ...
  "previewAttributesConfig": {
    "textFontSize": 12,
    "order": false,				 // "true" or "false"  
    "size": false,
    "quality": false,
    "yawAngle": false,
    "pitchAngle": false,
    "rollAngle": false,
    "watchlistMemberId": false,
    "watchlistMemberName": true,
    "watchlistName": true,
    "matchingScore": true,
    "age": false,
    "gender": false,
    "templateQuality": false,
    "faceMaskStatus": false,
    "faceMaskConfidence": false
  }  
  ...
}