Skip to main content

Save and Retrieve Data

To receive file paths for images, PDF freight reports, etc., you must command the device to save the dimension and view data. This data is then saved to the local hard drive on the machine, and can be retrieved asynchronously.

The Snapshot command returns the filepaths that can be used to retrieve the corresponding data.

Timing of save command

The save command, called Snapshot, saves the data that produced the dimensioning result. That data is stored in RAM until the next Dimension command is sent. Thus there is no concern about how quickly a Snapshot command is sent after its Dimension counterpart has been executed. Freight can be removed immediately after it is dimmed.

Freight reports, freight labels, etc.

All files pertaining to the dimensioned freight are only generated upon a successful Snapshot command.

<Snapshot/>​

Request​

Endpoint​

Request the machine with local IP address 10.1.1.2, set to port 7100, to save the data it has just collected.

GEThttp://10.1.1.2:7100/Snapshot


Desired response format:

Accept: application/xml (DEFAULT)

Response​

The response will return a code of 0 to mean that the request completed without errors. The major nodes of Request/Snapshot/Directory are:

  • Xmls: Info.xml contains all the data returned from the Dimension command. It is useful for correlating that the dim data received from that command is the same data that is stored in the filepath received from Snapshot.
  • Clouds: The raw data used to compute the dimension results. Box.pcd is the Augmented Reality box that is drawn on top of the freight in the viewer (and in marked images). Combined combines both sensor viewpoints ("*-raw.pcd" files) with "box.pcd".
  • Images: All images collected at time of scan. Additionally, marked images have the AR box drawn on them.
  • Misc: Misc will include additional files generated. Since Freight Reports and Freight labels are optional, they are included in Misc instead of their own dedicated category.
<Responses>
  <Snapshot code="0">
    <Directory>
      <Misc>
        <Path>Jul-6_21-25-32_2018/Freight-Report.pdf</Path>
      </Misc>
      <Clouds>
        <Path>Jul-6_21-25-32_2018/005337361647-raw.pcd</Path>
        <Path>Jul-6_21-25-32_2018/combined-raw.pcd</Path>
        <Path>Jul-6_21-25-32_2018/005302461647-raw.pcd</Path>
        <Path>Jul-6_21-25-32_2018/box.pcd</Path>
      </Clouds>
      <Images>
        <Path>Jul-6_21-25-32_2018/cameraName-0.png</Path>
        <Path>Jul-6_21-25-32_2018/cameraName-0-marked.png</Path>
        <Path>Jul-6_21-25-32_2018/cameraName-1.png</Path>
        <Path>Jul-6_21-25-32_2018/cameraName-1-marked.png</Path>
        <Path>Jul-6_21-25-32_2018/Image-from-webcam.png</Path>
      </Images>
      <Xmls>
        <Path>Jul-6_21-25-32_2018/info.xml</Path>
      </Xmls>
    </Directory>
  </Snapshot> 
</Responses>

<File/>​

A File command is used to retrieve files saved by the Snapshot command. Only one file can be retrieved at a time, so this will usually involve multiple

GET
requests to retrieve all desired files.

Limited permissions

A File command can only retrieve files within the '~/Cargo-Spectre/' folder on the machine, as this is where all Cargo Spectre data is saved to. For this reason, File cannot be used with absolute paths. Only relative paths from ~/Cargo-Spectre/ will work.

Request​

Endpoint​

Request a dimension from a machine with local IP address 10.1.1.2 set to port 7100.

GEThttp://10.1.1.2:7100/File/path-to-file


Example:

GEThttp://10.1.1.2:7100/File/Jul-6_21-25-32_2018/Image-from-webcam.png


Response​

The response will return the file in question with various content-type headers depending on the file in question. Cargo Spectre Dimensioners generate a set number of file types.

Content Type Change

On older versions of the software (prior to 3.0.100) the content type for PDFs and PCDs is text/plain.

Images are returned as content-type image/jpeg if they are saved in this format. Saving images as JPGs requires that the appropriate setting is ticked in the device's settings.

<ListDirectory/>​

A ListDirectory command can be used to retrieve a list of all data saved via Snapshot on the machine. The command can optionally accept certain parameters, shown below.

Parameters​

The ListDirectory command can take a few parameters.

InlineInfo controls whether the dimension data for the particular snapshot will be appended inline or not. Without it, a separate File command to retrieve the info.xml file will need to be sent to retrieve that data.

Type: Bool

Default: false

Request with No Parameters​

Dimension info will be sent inline with the response to alleviate the need for multiple commands.

Endpoint​

Request the machine with local IP address 10.1.1.2, set to port 7100, to view all snapshot directories in the Cargo-Spectre logo.

GEThttp://10.1.1.2:7100/ListDirectory


Header​

Desired response format:

Accept: application/xml (DEFAULT)

Response with No Parameters​

The response will return a code of 0 to mean that the request completed without errors. The major nodes of Request/ListDirectory are:

  • code: "0" indicates no error.
  • Directory: An array of all directories that fall within the search criteria.
    • "iso8601": ISO8601-formatted date of the directory. In XML this is an attribute of the Directory.
    • "name": Directory name, usually the date in the format "Mon-Day_hr-min-sec_Year". In XML this is an attribute of the Directory.
    • "Path": An array of files in the directory.
This is a particularly large response
<Responses>
  <ListDirectory code="0">
    <Directory iso8601="2022-04-15T23:10:16" name="Apr-15_23-10-16_2022">
      <Path>Apr-15_23-10-16_2022/Kinect4a-1-marked.jpg</Path>
      <Path>Apr-15_23-10-16_2022/Kinect4a-2-marked.jpg</Path>
      <Path>Apr-15_23-10-16_2022/box.pcd</Path>
      <Path>Apr-15_23-10-16_2022/Kinect4a-2.jpg</Path>
      <Path>Apr-15_23-10-16_2022/combined-raw.pcd</Path>
      <Path>Apr-15_23-10-16_2022/Kinect4a-0-marked.jpg</Path>
      <Path>Apr-15_23-10-16_2022/info.xml</Path>
      <Path>Apr-15_23-10-16_2022/Kinect4a-0.jpg</Path>
      <Path>Apr-15_23-10-16_2022/Kinect4a-1.jpg</Path>
    </Directory>
    <Directory iso8601="2022-04-15T23:12:56" name="Apr-15_23-12-56_2022">
      <Path>Apr-15_23-12-56_2022/Kinect4a-1-marked.jpg</Path>
      <Path>Apr-15_23-12-56_2022/Kinect4a-2-marked.jpg</Path>
      <Path>Apr-15_23-12-56_2022/box.pcd</Path>
      <Path>Apr-15_23-12-56_2022/Kinect4a-2.jpg</Path>
      <Path>Apr-15_23-12-56_2022/combined-raw.pcd</Path>
      <Path>Apr-15_23-12-56_2022/Kinect4a-0-marked.jpg</Path>
      <Path>Apr-15_23-12-56_2022/info.xml</Path>
      <Path>Apr-15_23-12-56_2022/Kinect4a-0.jpg</Path>
      <Path>Apr-15_23-12-56_2022/Kinect4a-1.jpg</Path>
    </Directory>
  </ListDirectory>
</Responses>

Request with Inline Info​

Endpoint​

Request the machine with local IP address 10.1.1.2, set to port 7100, to view all snapshot directories in the Cargo-Spectre logo. Dimension info will be sent inline - the File command will not need to be used to retrieve the info.xml file and its contents as it will just be appended here.

GEThttp://10.1.1.2:7100/ListDirectory?InlineInfo=true


Header​

Desired response format:

Accept: application/xml (DEFAULT)

Response with Inline Info​

The response will return a code of 0 to mean that the request completed without errors. The major nodes of Request/ListDirectory are:

  • code: "0" indicates no error.
  • Directory: An array of all directories that fall within the search criteria.
    • "iso8601": ISO8601-formatted date of the directory. In XML this is an attribute of the Directory.
    • "name": Directory name, usually the date in the format "Mon-Day_hr-min-sec_Year". In XML this is an attribute of the Directory.
    • "Path": An array of files in the directory.
    • (Optional)"Info": The dimensions, weight, units, and barcode of that scan can be attached. This data resides in the info.xml file. This output can be optionally turned on.
This is a particularly large response
<Responses>
  <ListDirectory code="0">
    <Directory iso8601="2022-04-15T23:10:16" name="Apr-15_23-10-16_2022">
      <Path>Apr-15_23-10-16_2022/Kinect4a-1-marked.jpg</Path>
      <Path>Apr-15_23-10-16_2022/Kinect4a-2-marked.jpg</Path>
      <Path>Apr-15_23-10-16_2022/box.pcd</Path>
      <Path>Apr-15_23-10-16_2022/Kinect4a-2.jpg</Path>
      <Path>Apr-15_23-10-16_2022/combined-raw.pcd</Path>
      <Path>Apr-15_23-10-16_2022/Kinect4a-0-marked.jpg</Path>
      <Path>Apr-15_23-10-16_2022/info.xml</Path>
      <Path>Apr-15_23-10-16_2022/Kinect4a-0.jpg</Path>
      <Path>Apr-15_23-10-16_2022/Kinect4a-1.jpg</Path>
      <Info>
        <Dimensions>
          <Length>59.0</Length>
          <Width>40.5</Width>
          <Height>24.0</Height>
          <Volume>33.1875</Volume>
          <Density>0</Density>
          <Weight>
            <Net>0</Net>
            <Gross>0</Gross>
            <Tare>0</Tare>
          </Weight>
          <Barcode/>
        </Dimensions>
        <Units>
          <Length>inches</Length>
          <Volume>cubic feet</Volume>
          <Weight>lb</Weight>
          <Density>lb/cubic feet</Density>
        </Units>
        <Scanner>
          <Mode>CARGO</Mode>
          <Certified>null</Certified>
        </Scanner>
      </Info>
    </Directory>
    <Directory iso8601="2022-04-15T23:12:56" name="Apr-15_23-12-56_2022">
      <Path>Apr-15_23-12-56_2022/Kinect4a-1-marked.jpg</Path>
      <Path>Apr-15_23-12-56_2022/Kinect4a-2-marked.jpg</Path>
      <Path>Apr-15_23-12-56_2022/box.pcd</Path>
      <Path>Apr-15_23-12-56_2022/Kinect4a-2.jpg</Path>
      <Path>Apr-15_23-12-56_2022/combined-raw.pcd</Path>
      <Path>Apr-15_23-12-56_2022/Kinect4a-0-marked.jpg</Path>
      <Path>Apr-15_23-12-56_2022/info.xml</Path>
      <Path>Apr-15_23-12-56_2022/Kinect4a-0.jpg</Path>
      <Path>Apr-15_23-12-56_2022/Kinect4a-1.jpg</Path>
      <Info>
        <Dimensions>
          <Length>61.5</Length>
          <Width>38.0</Width>
          <Height>24.0</Height>
          <Volume>32.4583</Volume>
          <Weight>
            <Net>0</Net>
            <Gross>0</Gross>
            <Tare>0</Tare>
          </Weight>
          <Density>0</Density>
          <Barcode/>
        </Dimensions>
        <Units>
          <Length>inches</Length>
          <Volume>cubic feet</Volume>
          <Weight>lb</Weight>
          <Density>lb/cubic feet</Density>
        </Units>
        <Scanner>
          <Mode>CARGO</Mode>
          <Certified>16-040A1</Certified>
        </Scanner>
      </Info>
    </Directory>
  </ListDirectory>
</Responses>

Request With Specified End Date and No Inline Info​

Begin and End are both options

This example shows what the API looks like with End specified, but note that ListDirectory parameters also include a Begin parameter to specify an inclusive start date. Both or just one can be used.

Endpoint​

Request the machine with local IP address 10.1.1.2, set to port 7100, to view all snapshot directories in the Cargo-Spectre logo that occurred prior to the date specified.

Dimension info will not be sent inline - the File command will need to be used to retrieve the info.xml file and its contents.

GEThttp://10.1.1.2:7100/ListDirectory?InlineInfo=false&End=2022-04-15T23:11:56


Header​

Desired response format:

Accept: application/xml (DEFAULT)

Response with Specified End Date and No Inline Info​

The response will return a code of 0 to mean that the request completed without errors. The End parameter is supplied but the time is changed to one minute earlier to receive only the first directory.

The major nodes of Request/ListDirectory are:

  • code: "0" indicates no error.
  • Directory: An array of all directories that fall within the search criteria.
    • "iso8601": ISO8601-formatted date of the directory. In XML this is an attribute of the Directory.
    • "name": Directory name, usually the date in the format "Mon-Day_hr-min-sec_Year". In XML this is an attribute of the Directory.
    • "Path": An array of files in the directory.
<Responses>
  <ListDirectory code="0">
    <Directory iso8601="2022-04-15T23:10:16" name="Apr-15_23-10-16_2022">
      <Path>Apr-15_23-10-16_2022/Kinect4a-1-marked.jpg</Path>
      <Path>Apr-15_23-10-16_2022/Kinect4a-2-marked.jpg</Path>
      <Path>Apr-15_23-10-16_2022/box.pcd</Path>
      <Path>Apr-15_23-10-16_2022/Kinect4a-2.jpg</Path>
      <Path>Apr-15_23-10-16_2022/combined-raw.pcd</Path>
      <Path>Apr-15_23-10-16_2022/Kinect4a-0-marked.jpg</Path>
      <Path>Apr-15_23-10-16_2022/info.xml</Path>
      <Path>Apr-15_23-10-16_2022/Kinect4a-0.jpg</Path>
      <Path>Apr-15_23-10-16_2022/Kinect4a-1.jpg</Path>
    </Directory>
  </ListDirectory>
</Responses>

<Upload/>​

This command will upload the most recent Snapshot to the Cargo Spectre cloud.

Interaction with Other API Commands

The Upload command requires certain prerequisites to be fulfilled.

  • The system must have a valid snapshot in memory. This requires prior Dimension and Snapshot commands to have been sent before it can be used. If a snapshot has not been taken, the command will return an error.
  • Once an upload on the current snapshot has taken place successfully, the system will log that snapshot as having been uploaded already. To avoid duplication of data on the cloud, snapshots can only be uploaded once. This command will return a warning if the most recent Snapshot has already been uploaded to the cloud.
  • To re-upload the same target, simply repeat the full Dimension+Snapshot+Upload loop.

Request​

Request to upload the most recent Dimension + Snapshot data to the cloud, with a machine with local IP address 10.1.1.2 set to port 7100.

Endpoint​

GEThttp://10.1.1.2:7100/Upload


Header​

Desired response format:

Accept: application/xml (DEFAULT)

Response​

The response will return a code of 0 to mean that the request completed without errors. The major nodes of Request/Upload/ are:

  • Info: This is a duplicate of the Dimension command's data response. This is done so that if this command is sent separately from the other prerequisite commands, the user can validate which scan was uploaded.
  • Server: This shows cloud-specific parameters associated with the upload, detailed as below.
    • status: string message of successful upload or not.
    • error: string message of the error if unsuccessful.
    • cargoID: int ID of the uploaded cargo. This would allow a user logged in to spectre-licensing.com to navigate to /Cargo/Details/cargoID to view the uploaded cargo.
    • scanGUID: string GUID associated with files uploaded for the scan. Any filename listed under Snapshot can be retrieved from the cloud not with its local machine filepath, but rather by constructing the following URL: https://cargospectre.blob.core.windows.net/scans/organization-name/scanGUID/filename.
    • shareGUID: Empty unless the AutoShare parameter is set to true in the Upload command. See below for more information.
    • scanDate: ISO8601 date of the scan.
<Responses>
  <Upload code="0"/>
    <Info>
      <Dimensions>
        <Length>59.5</Length>
        <Width>45.0</Width>
        <Height>25.5</Height>
        <Volume>39.5117</Volume>
        <Weight>
          <Net>0</Net>
          <Gross>0</Gross>
          <Tare/>
        </Weight>
        <Density>0</Density>
        <Barcode/>
      </Dimensions>
      <Units>
        <Length>inches</Length>
        <Volume>cubic feet</Volume>
        <Weight>lb</Weight>
        <Density>lb/cubic feet</Density>
      </Units>
      <Scanner>
        <Mode>CARGO</Mode>
        <Certified>16-040A1</Certified>
      </Scanner>
    </Info>
    <Server>
      <status>Record created successfully</status>
      <cargoID>12345</cargoID>
      <error>null</error>
      <scanGUID>12345-6789-0123-4567-890123456789</scanGUID>
      <shareGUID/>
      <scanDate>2022-04-15T23:10:16</scanDate>
    </Server>
    </Upload>
</Responses>

Request with AutoShare Parameter​

If the user desires to automatically create a share link that can be shared outside of the organization, the AutoShare parameter can be set to true. This will return a shareGUID in the response, which can be used to construct a share link.

The share link will be viewable by anyone with the link, regardless of whether they are logged in to spectre-licensing.com. The share link will expire after a set period of time.

Endpoint​

Request a dimension from a machine with local IP address 10.1.1.2 set to port 7100.

GEThttp://10.1.1.2:7100/Upload?AutoShare=true


Header​

Desired response format:

Accept: application/xml (DEFAULT)

Response with AutoShare Parameter​

The response will return a code of 0 to mean that the request completed without errors. The major nodes of Request/Upload/ are:

  • Info: This is a duplicate of the Dimension command's data response. This is done so that if this command is sent separately from the other prerequisite commands, the user can validate which scan was uploaded.
  • Server: This shows cloud-specific parameters associated with the upload, detailed as below.
    • status: string message of successful upload or not.
    • error: string message of the error if unsuccessful.
    • cargoID: int ID of the uploaded cargo. This would allow a user logged in to spectre-licensing.com to navigate to https://spectre-licensing.com/Cargo/Details/cargoID to view the uploaded cargo.
    • scanGUID: string GUID associated with files uploaded for the scan. Any filename listed under Snapshot can be retrieved from the cloud not with its local machine filepath, but rather by constructing the following URL: https://cargospectre.blob.core.windows.net/scans/organization-name/scanGUID/filename.
    • shareGUID: string GUID associated with the share link. This can be used to construct a share link that can be shared outside of the organization. The share link will expire after a set period of time. The URL will have the following format: https://spectre-licensing.com/Cargo/Shared/shareGUID.
    • scanDate: ISO8601 date of the scan.
<Responses>
  <Upload code="0"/>
    <Info>
      <Dimensions>
        <Length>59.5</Length>
        <Width>45.0</Width>
        <Height>25.5</Height>
        <Volume>39.5117</Volume>
        <Weight>
          <Net></Net>
          <Gross>0</Gross>
          <Tare/>
        </Weight>
        <Density>0</Density>
        <Barcode/>
      </Dimensions>
      <Units>
        <Length>inches</Length>
        <Volume>cubic feet</Volume>
        <Weight>lb</Weight>
        <Density>lb/cubic feet</Density>
      </Units>
      <Scanner>
        <Mode>CARGO</Mode>
        <Certified>16-040A1</Certified>
      </Scanner>
    </Info>
    <Server>
      <status>Record created successfully</status>
      <cargoID>12345</cargoID>
      <error>null</error>
      <scanGUID>12345-6789-0123-4567-890123456789</scanGUID>
      <shareGUID>423423432-432432-432432-432432-432432</shareGUID>
      <scanDate>2022-04-15T23:10:16</scanDate>
    </Server>
    </Upload>
</Responses>