Nx Witness allows you to retrieve a thumbnail from the camera, in the form of a static image, through the API. Refer to GET/ec2/cameraThumbnail under the System API section in the API Documentation.
The basic format of the API call is as follows:
http://<server_ip>:<port>/ec2/cameraThumbnail?<cameraid><options>
Substitute the generic variables with your specifications. Refer to the Camera Identifiers article to learn how to find your camera ID.
Options
For the <options> portion, you have the ability to add specific details using the variables described here. It is optional to include any of these in your API request. If not included, they will fall to their default values as specified in the list below.
- time — Enter the timestamp of the requested image. It can either be a string containing time in milliseconds since epoch, or in local server time formatted in
YYYY-MM-DDTHH:mm:ss.zzz.- By default, the time will be “latest”, where the thumbnail will be either from the live stream or the most recent image from the archive.
- rotate — Enter the desired image orientation. The value can be 90, 290, or 270.
- By default, orientation is determined by the camera settings.
- height — Enter the desired image height. The value should not be less than 128.
- By default, it uses the original frame size.
- width — Enter the desired image width. The value should not be less than 128. If the height is specified, the width will be calculated based on the aspect ratio.
- By default, it uses the original frame size.
- imageFormat — Enter the desired image format. The format can be png, jpg, tif, or raw.
- By default, it is “JpgFormat”.
- method — Determines when to retrieve the thumbnail nearest to the given timestamp. The value can be ‘before’, ‘precise’ and ‘after’. Retrieving the thumbnail at the exact timestamp can be costly resource-wise.
- By default, it is set to ‘after’.
- streamSelectionMode — Determines which stream is selected. The value can be ‘auto’, ‘forcedPrimary’, ‘forcedSecondary’, or ‘sameAsMotion’.
- By default, it is set to ‘auto’.
- aspectRatio — Determines the aspect ratio of the thumbnail. The value can be ‘auto’ or ‘source’.
- By default, it is set to ‘auto’.
- ignoreExternalArchive — If used and the "time" parameter has value set to "latest", the image will not be downloaded from the archive of the dts-based devices.
- tolerant — If used and the "time" parameter is set to a timestamp that doesn’t have an existing archive, the next or previous available image (in accordance with the "method" parameter) will be obtained.
- crop — Applies cropping to the source image. Parameter defines rect in range [0..1]. Format: 'left,top,widthxheight'.
- Example: '0.5,0.4,0.25x0.3'.
- format — Determines the data format. The format can be json, ubjson, xml, or csv.
- By default, the data format is ‘json’.
Examples of API Calls
time is specified:
https://localhost:7001/ec2/cameraThumbnail?cameraId=d0gf4a56-9768-dc5b-cb7e-987db37cd2d8&time=2020-05-22T12:00:00.000
time, imageFormat, and streamSelectionMode are specified.
https://10.1.5.182:7011/ec2/cameraThumbnail?cameraId=d0gf4a56-9768-dc5b-cb7e-987db37cd2d8&time=2020-05-22T12:00:00.000&imageFormat=png&streamSelectionMode=forcedPrimary
FAQ
- Why is the image size of the thumbnail I sometimes receive smaller than what I requested?
- This can happen when your camera’s primary stream is unavailable at the timestamp you requested. Therefore, the thumbnail is retrieved from the camera’s secondary stream. Include the following option in your API call to force your primary stream to provide the thumbnail:
&streamSelectionMode=forcedPrimary
- This can happen when your camera’s primary stream is unavailable at the timestamp you requested. Therefore, the thumbnail is retrieved from the camera’s secondary stream. Include the following option in your API call to force your primary stream to provide the thumbnail:
- Why am I getting a “204 No Content” response?
- A common explanation can be that the timestamp you included doesn’t exist in the archive. Try using another timestamp. If that doesn’t help, please contact support.
- Does anything happen to the quality of the image when it’s exported?
- No, the Nx Server does not compress the image during export. The quality of the image will be the same as the source.
Comments
0 comments
Article is closed for comments.