HemoSpat Coordinate Exchange Format

Format Version: 1.0
File Extension: .hscx
Date: 20 September 2016
Author: Andy Maloney <andy@forident.com>

This file describes the HemoSpat Coordinate Exchange file format. This is used to map the HemoSpat coordinate system to the coordinate system of the importing software. This allows HemoSpat to translate and rotate the model on export so that when it is imported into 3rd-party software it appears in the correct location with the correct orientation and scale.

Once this mapping has been created, any changes to the HemoSpat analysis can be imported into the point cloud software without having to reposition the models again. This makes collaboration easier when working on a crime scene reconstruction - a point cloud expert can work with the point cloud data and a bloodstain analyst can focus on their impact pattern analysis.

Any of HemoSpat's 3D exporters (COLLADA, DXF, OBJ, PLY, and VRML) can use this data format.

The file is a simple text file using standard JSON. The file should use the .hscx extension.

Here is a full example:

{
  "header": {
    "created": {
      "date": "2016-07-22T22:33:07Z",
      "software": {
        "name": "SuperSoftware",
        "version": "1.6.1"
      }
    },
    "formatVersion": "1.0"
  },
  "data": {
    "description": "Point cloud of 123 Foo St. living room",
    "pointCloudFileName": "123 Foo.pts",
    "units": "cm",
    "coordinateSystem": {
      "out": "x",
      "right": "y",
      "up": "z"
    },
    "points": {
      "origin": {
        "x": 54.93,
        "y": 153.41,
        "z": 34200.2
      },
      "front": {
        "x": 108.11,
        "y": 51.58,
        "z": 34248.9
      },
      "leftEdge": {
        "x": 55.39,
        "y": 154.47,
        "z": 34254.1
      }
    }
  }
}

header [object]

{
  "header": {
    "created": {
      "date": "2016-07-22T22:33:07Z",
      "software": {
        "name": "SuperSoftware",
        "version": "1.6.1"
      }
    },
    "formatVersion": "1.0"
  },
  ...
}

created [object]

This section contains information about the software which created this file.

date [string]

Date this file was written. This is in ISO 8601 extended format: either YYYY-MM-DDTHH:mm:ss or YYYY-MM-DDTHH:mm:ssTZD.

Examples: "1997-07-16T19:20:30+01:00", "2016-07-22T22:33:07Z"

software [object]

name [string]
The name of the software.
version [string]
The version number of the software.

formatVersion [string]

This is the version of the .hscx file format.

data [object]

{
   ...
  "data": {
    "description": "Point cloud of 123 Foo St. living room",
    "pointCloudFileName": "123 Foo.pts",
    "units": "cm",
    "coordinateSystem": {
      ...
    },
    "points": {
      ...
    }
  }
}
This section contains information about the point cloud and its coordinate system.

description [string] [optional]

An optional description of the file. This may be displayed in the HemoSpat exporter interface.

pointCloudFileName [string] [optional]

The point cloud file name. This may be displayed in the HemoSpat exporter interface.

units [string]

Units used in the point cloud. This will be used to convert (scale) from HemoSpat's internal units ("cm") to the importing software's units.

Accepted: "mm", "cm", "m", "in", "ft", "ft (US)", "yd"

coordinateSystem [object]

{
   "coordinateSystem": {
      "out": "x",
      "right": "y",
      "up": "z"
   },
}

This section tells HemoSpat what coordinate system is being used in the model or point cloud. HemoSpat uses the Right Hand Coordinate system (+y right, +z up):

Right Handed Coordinate System

If the model or point cloud uses another system - Left Hand (+x right, +z up) or OpenGL (+x right, +y up) for example - then the information in this section is used to transform the model on output.

out [string]

Identifies which axis is positive out from the origin and in to the camera/viewer ("x" in the diagram above).

Accepted: "x", "y", "z"

right [string]

Identifies which axis is positive in the right direction ("y" in the diagram above).

Accepted: "x", "y", "z"

up [object]

Identifies which axis is positive in the up direction ("z" in the diagram above).

Accepted: "x", "y", "z"

Note that each of "x", "y", and "z" may only be used once in this section in order to properly define the coordinate system.

points [object]

{
  ...
  "points": {
    "origin": {
      "x": 54.93,
      "y": 153.41,
      "z": 34200.2
    },
    "front": {
      "x": 108.11,
      "y": 51.58,
      "z": 34248.9
    },
    "leftEdge": {
      "x": 55.39,
      "y": 154.47,
      "z": 34254.1
    }
  }
}

The units for these points are the one specified by the units key and the coordinate system is defined by the coordinateSystem section.

origin [object]

The point HemoSpat's origin should map to in the point cloud or model.
x, y, and z [number]

front [object]

Any point on the surface of what HemoSpat would consider the "front wall". This is the surface whose bottom-left corner is the room origin. The normal of this surface is the "in" axis of the coordinate system.
x, y, and z [number]

leftEdge [object]

Any point along the left edge of the "front wall". The "front wall" is the surface whose bottom-left corner is the room origin.
x, y, and z [number]



Changes

  • 1.0 [20 September 2016]
    • initial version