Skip to main content

Scene intelligence API

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to Device Configuration APIs.

Description​

The Scene intelligence API makes it possible to control video features that enhance the appearance of detected objects compared to the background. It also provides per-channel configuration options for background appearance settings.

For optimal viewing performance, use the rotation parameter to make objects appear in their natural, upright orientation. If the camera is mounted inverted or sideways, use the corresponding rotation angle.

Use cases​

Configure background appearance settings​

The API controls the background appearance relative to detected objects. Reducing contrast and color saturation in the background lowers bitrate and can improve the visibility of objects of interest in the video stream.

List channels supporting background appearance​

List channels that support background appearance features.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/scene-intelligence/v1/availableChannels
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": [
        "0"
    ],
    "information": [],
    "warnings": []
}

Get current background appearance settings for a channel​

Retrieve the current background appearance configuration for channel 0.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/scene-intelligence/v1/backgroundAppearance/0
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "channel": "0",
        "supported": true,
        "strength": 0.5,
        "saturationReduction": true,
        "sharpnessReduction": false
    },
    "information": [],
    "warnings": []
}
curl -sS --digest -u <user>:<pass> \
  'http://DEVICE/config/rest/scene-intelligence/v1/backgroundAppearance/0' \
  -H 'accept: application/json' --insecure

Configure background appearance strength for a channel​

Adjust the strength of the background appearance effect for channel 0.

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/scene-intelligence/v1/backgroundAppearance/0/strength \
  --data '{
    "data": 0.7
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "information": [],
    "warnings": []
}
curl -sS --digest -u <user>:<pass> \
  -X PATCH 'http://DEVICE/config/rest/scene-intelligence/v1/backgroundAppearance/0/strength' \
  -H 'content-type: application/json' \
  --data '{"data":0.7}' --insecure

Enable saturation reduction in background for a channel​

Enable or disable color saturation reduction in the background for channel 0.

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/scene-intelligence/v1/backgroundAppearance/0/saturationReduction \
  --data '{
    "data": true
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "information": [],
    "warnings": []
}
curl -sS --digest -u <user>:<pass> \
  -X PATCH 'http://DEVICE/config/rest/scene-intelligence/v1/backgroundAppearance/0/saturationReduction' \
  -H 'content-type: application/json' \
  --data '{"data":true}' --insecure

Configure multiple background appearance settings for a channel​

Set multiple background appearance properties at once for channel 0.

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/scene-intelligence/v1/backgroundAppearance/0 \
  --data '{
    "data": {
        "strength": 0.8,
        "saturationReduction": true,
        "sharpnessReduction": true
    }
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "information": [],
    "warnings": []
}
curl -sS --digest -u <user>:<pass> \
  -X PATCH 'http://DEVICE/config/rest/scene-intelligence/v1/backgroundAppearance/0' \
  -H 'content-type: application/json' \
  --data '{"data":{"strength":0.8,"saturationReduction":true,"sharpnessReduction":true}}' \
  --insecure

API definition​

Structure​

scene-intelligence.v1 (Root Entity)
    ├── availableChannels (Property)
    ├── backgroundAppearance (Entity Collection)
        ├── channel (Property)
        ├── saturationReduction (Property)
        ├── sharpnessReduction (Property)
        ├── strength (Property)
        ├── supported (Property)

Entities​

scene-intelligence.v1​

  • Description: Configuration root entity
  • Type: Singleton
  • Operations
    • GET
    • SET
  • Attributes
    • Dynamic Support: No
Properties​
availableChannels​
  • Description: List of video channel identifiers that support background appearance features.
  • Datatype: ChannelList
  • Operations
    • GET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​

This entity has no actions.

scene-intelligence.v1.backgroundAppearance​

  • Description: Background appearance settings per video channel.
  • Type: Collection (Key Property: channel)
  • Operations
    • GET
    • SET
  • Attributes
    • Dynamic Support: No
Properties​
channel​
  • Description: Video channel identifier ("0", "1").
  • Datatype: string
  • Operations
    • GET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
saturationReduction​
  • Description: Enables reduction of color saturation in the background to improve object visibility.
  • Datatype: boolean
  • Operations
    • GET
    • SET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
sharpnessReduction​
  • Description: Enables reduction of sharpness in the background to emphasize detected objects.
  • Datatype: boolean
  • Operations
    • GET
    • SET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
strength​
  • Description: Adjusts the intensity of the background appearance effect; higher values increase separation between objects and background.
  • Datatype: UnitNumber
  • Operations
    • GET
    • SET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
supported​
  • Description: Indicates availability of background appearance features based on camera configuration (such as capture mode) and product capabilities.
  • Datatype: boolean
  • Operations
    • GET
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​

This entity has no actions.

Data Types​

ChannelList​

  • Description: Array of channel identifiers
  • Type: array
  • Element type: string
  • Null Value: No

UnitNumber​

  • Description: A number between 0 and 1
  • Type: number
  • Minimum Value: 0
  • Maximum Value: 1