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.

GET http://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 request 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.

GET http://10.1.1.2:7100/File/path-to-file

Example:

GET http://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.

GET http://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.

GET http://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.

GET http://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>