top of page

Images Input

Route for sending a image data to Trax

API endpoint for submitting Images information as part of Visit Data

PUT /api/:version_number/:project_name/session/:session_uid/scenes/:scene_uid/images/:my-image-uid

curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" -X PUT https://services.traxretail.com/api/v4/my-project/sessions/my-session-UID/scenes/my-scene-UID/images/my-image-uid

Supported Protocol: HTTPS

PUT

Request Headers

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

Content-Type string

Value: 'multipart/form-data'

Query Parameters

version_number string *

The current implemented API version. <Major> version (e.g. 'v4')

 

project_name string *

Project name as provided by Trax

session_uid string *

UUID generated by the client for the session.

The session UID will be generated at the beginning of the Session and will be used throughout the session

scene_uid string *

UUID generated by the client for the scene.

The scene UID will be generated at the beginning of the Scene and will be used throughout the scene

image_uid string *

UUID generated by the client for each image

Request Details

Mandatory fields marked indicated by

*

file FILE - JPEG *

The image being uploaded, must be JPEG format. The recommended resolution of an image is 8 mega-pixel, with aspect ratio 4:3 or 16:9. The maximum size of an image is 50 MB.

store_number string (100) *

Client's Store unique identifier, as provided in Stores

visit_date string (YYYY-MM-DD)*

The date of the visit by local time zone

captured_by string

Client identifier for the entity taking the image. (e.g. if fixed cameras are used, this should identify the specific camera)

capture_time number (Epoch Unix Time timestamp)*

The Unix Epoch timestamp of the session end time in the client application

local_tz_offset number*

The local timezone offset for UTC in minutes (e.g. for PST will be -420)

task_code string *

Task Code - Scene types that have been configured in coordination with Trax implementation team

image_properties Object

Trax Image Recognition algorithms are at optimal performance when the image properties are available. While the following section is not mandatory as part of the Image route, it is highly recommended to send this data. Sending the following data will improve accuracy and speed of the analysis results. The image_property fields are:
 

latitude number (float)

GPS latitude coordinate (in degrees). Trax recommends to populate the GPS location values, latitude &longitude which will aid in visit location in dashboards, visit fraud detection, store discovery & more​

longitude number (float)

GPS longitude coordinate (in degrees). Trax recommends to populate the GPS location values, latitude &longitude which will aid in visit location in dashboards, visit fraud detection, store discovery & more

camera_orientation number (float[4])

A quaternion representing the device's attitude ordered (w,x,y,z). Also known as Direction

It represents an estimate of the camera's orientation with respect to the world. In a regular smartphone the orientation is obtained from device sensors (Android: SensorManager iOS: CMMotionManager). In a motion-tracking context (e.g. Tango device/Robot), the orientation is the rotation component of the camera's pose.

Trax recommends to populate the angles value for improving the quality of image rectification and stitching that are used in the recognition and analysis process. It includes the compass direction which helps characterize the store. 

e.g.

(0.99608138, 0.08358118, 0.01152329, 0.02651957)

automatic_screen_rotation boolean

The setting of the screen rotation. True if enabled. Enhances recognition & image visualization

camera_position number (float[3])

The in-store location coordinates. Also known as Translation, Shift, Location. The value is an ordered x,y,z of the pose of the current frame with reference to the base frame. The axes of the base frame coincide with the base directions in camera orientation(3). The coordinates values are in meters. The camera pose should be relative to the store's coordinate system, if available. If a store coordinate system is not available, the coordinate system should be stable for the entire scene (e.g. using Tango's COORDINATE_FRAME_START_OF_SERVICE)

This value should be sent in case the system supports in-store navigation.

This data enhances stitching quality & in-store location related features. 

e.g.(x,y,z)

where (14.3, 0.5, 1.51)

device_name string

The name of the device. This data helps in investigation and reports. It shortens the investigation time & focuses the investigation to increase the chance of full scenario recovery. 

camera_maker string

The camera maker. This data helps in investigation and reports. It shortens the investigation time & focuses the investigation to increase the chance of full scenario recovery. 

exposure_time string

the number of seconds of exposure time/shutter speed. 

Enhance recognition & image visualization. 

e.g. 

1/19 sec., 1/50 sec.

camera_maker string

The camera maker. This data helps in investigation and reports. It shortens the investigation time & focuses the investigation to increase the chance of full scenario recovery. 

iso string

The ISO used. Enhances recognition & image visualization.​

e.g.

ISO-64, ISO-100, ISO-200

f_stop string

The f-stop value represents the aperture setting used when capturing the image. Enhances recognition & image visualization

e.g.

f/2.7, f/1.4​

exposure_bias number

The exposure bias steps used for exposure compensation. Enhances recognition & image visualization.​

e.g.

2

35mm_focal_length number(float)

The 35mm focal length equivalent. Enhances recognition & image visualization.​

e.g.

26.82

flash_mode string

The camera flash mode when the image has been captured. Enhances recognition & image visualization.

Flash Options List

flash_energy number

Indicates the strobe energy at the time the image is captured (BCPS). Enhances recognition & image visualization.

e.g.

200

aperture number(float)

Aperture value. Enhances recognition & image visualization.

e.g.

2.28

compression number

Indicates the compression level applied to the image. Enhances recognition & image visualization.

Range: 0-100

e.g.

75

white_balance string

The image's white balance. Enhances recognition & image visualization.

e.g.

"cloudy-daylight"

metering_mode string

The camera's metering mode. Enhances recognition & image visualization.

EXIF properties (search for 'MeteringMode')

  • Unknown 

  • Average Center-weighted average Spot

  • Multi-spot

  • Multi-segment

  • Partial

  • Other

subject_distance number(float)

The subject distance in meters. Enhances recognition & image visualization.

e.g

1.5

resolution number(float)

Indicates the captured image resolution in megapixels. Enhances recognition & image visualization.

e.g.

8.0

os string

The operating system and its version. This data helps in investigation and reports. It shortens the investigation time & focuses the investigation to increase the chance of full scenario recovery.

calibration_matrix number(float[4])

Intrinsic camera calibration matrix - (fx, fy, cx, cy)

Open CV Camera Calibration

lens_distortion number(float[5])

Radial and tangential lens distortion values - (k1, k2, k3, p1, p2) 

Open CV Camera Calibration

angular_velocity number(float[3])

The rate of rotation in rad/s around a device's x, y, and z axes (wx, wy, wz).

Rotation is positive in the counter-clockwise direction; that is, an observer looking from some positive location on the x, y, or z axis at a device positioned on the origin would report positive rotation if the device appeared to be rotating counter-clockwise. This is the standard mathematical definition of positive rotation. 

https://en.wikipedia.org/wiki/Angular_velocity

https://developer.android.com/guide/topics/sensors/sensors_motion

https://developer.apple.com/documentation/scenekit/scnphysicsbody/1514770-angularvelocity

puzzle_mode Object

Overlap position data of captured photo, used by the stitching machine. The keys are as follows:

column number

Index of the column on the grid. First column (from the left) starts from 0. All photos from the same column should have the same column index.

row number

Index of the row on the grid. Top row starts from 0, and increases by one for each new row. All photos from the same row should have the same row index.

overlap_percent_h number(float)

Percentage of horizontal overlap with perviously taken photo

overlap_percent_v number(float)

Percentage of vertical overlap with perviously taken photo

Request Body

Mandatory fields marked indicated by

*

Response, Validation, and Errors

When uploading the Image, the Trax system runs numerous validations on the file to confirm it has all the necessary fields. If the upload is successful it will return a body with the following fields:

Image already received

  • Error Code: 409 - Conflict

  • Error: Image has already been received

Mandatory Variables

  • Error Code: 400 - Bad Request

  • Error:

missing mandatory field - <field_name>
OR
missing mandatory fields: - <field_name>,<field_name>...

 

Variable Types

  • Error Code: 400 - Bad Request

  • Error:

Invalid variable type:<field_name>-expected type: <expected_variable_type>
OR
Invalid variable types:<field_name>-expected type: <expected_variable_type>, <field_name>-expected type: <expected_variable_type>....

Image Size 

  • Error Code: 413- Payload Too Large

  • Error: Image is too large: <image_size> MB
    N.B.: maximum 50 MB
     

Image Type

  • Error Code: 400 - Bad Request

  • Error: Invalid image type:<image_type>

Incorrect Format

  • Error Code: 400 - Bad Request

  • Error:

Incorrect format field: <field_name>,
the correct format: <correct_format>

Lookup Value does not exist, Unknown Store

  • Error Code: 400 - Bad Request

  • Error:

example​

Unknown Store <request_store_identifier_>

Internal Error 

  • Error Code: 500 - Internal Server Error

  • Error: Trax Internal Error

Should there be issues with the upload, an error code and error will be returned. It will contain one the following errors based on failing the related validation:

original string

Link to the original image at full quality

medium string

Link to the image compressed to a medium file size

small string

Link to the image compressed to a small file size

Request Body Example

{

"original":"https://services.traxretail.com/

crypt/traxusint/iY8fLlVlT5orNHj

CcrX9lDh+TRz1Hsm68E/qcxRoc8rCz

QNpb1E6ZQz1KIO7zUw6Fk2GuQis8O63

9qrvWnBJMk1WrLXVi3KgTjLoIbn

6GYmWJWg==",

"medium":"https://services.traxretail.com/crypt/

traxusint/Do6DNNQGk368NBnCNqPkO0

sQqxyu8F9GoRFif4VR7KxhuEYdsC3je7r

QspPoAdR43DpttEi7OG9/kYQUe6/rmADw

KmIGOboZyCnvyeWkebmKdlhm/",

 

"small":"https://services.traxretail.com/crypt/

traxusint/3xwSGp2oVENoKY6BLNbip

xfB/xyll9IlbAomp4v7guLtLC9/

4TgrrkKCMWf5PjyalUaE1kDtOs3J8Ol

YKDrIhzJh2GH1iKwINmqPeV5V"

}

bottom of page