Best_Practice_Guide

This page should give programmers some recommendations on how to use the [X3p] file format efficiently and correct.

• Data Orientation
• Use of coordinate list representation
• Writing Line Profiles
  • Incremental x and y axes
  • Absolute x and y axes
• Binary Format
• Avoid Offsets
• Provide Meta Data

Data Orientation

When storing 2.5D data as a matrix i.e. a profile define by Z(u,v), the x-axis is usually associated with the u-coordinate of the matrix, the y-axis with the v-coordinate and the z-axis is the explicit coordinate of the matrix. In plain words: u,v are normally the pixel coordinates of your camera and z is the depth value.

The u to x and v to y association is not fixed and you can not rely on it when reading files. u and v only specify the neighbourship of your data points not their coordinates.

Use of coordinate list representation

Coordinate lists must only be used, when storing data points with no known topology. That means when you do not now the neighbourship relation of your sample points you should store it as a list and set the file type to "PCL" for pointcloud which is defined by the macro

OGPS_FEATURE_TYPE_POINTCLOUD_NAME

. Data sets like this are called Point Clouds and may have been created by a CMM (Coordinate Measuring Machine) or by a software that destroyed or lost the topology of the data set.

Writing Line Profiles

Line profiles have to be stored as matrix with the dimensions u,1,w. Storing line profiles as coordinate list creates an error.

For the representation of the global orientation of your profile you have two choices described in the following sections.

Incremental x and y axes

If you choose an incremental x and y axes your profile is initially parallel to the global x-axis, because the matrix u coordinate is associated to the global x coordinate. If you want to represent another spatial orientation of your profile, for example a profile parallel to y-axis, you have to set the rotation matrix appropriately. If your system for example is scanning along the y-axis, the rotation matrix must contain a positive 90° rotation around the z-axis to get the coordinates represented in the correct coordinate system.

Absolute x and y axes

When using absolute axes you can directly specify any orientation and shape of the scanned profile by giving an explicit x and y coordinate to each point. The matrix u coordinate then only represent the neighbourship of your data points and is not related any more to the x axis of your coordinate system.

With absolute axes you can even store free shape profiles e.g. a spiral scan of a surface.

Binary Format

Use binary format when saving more than 10000 points: This will reduce the resulting file size and increase the writing and reading speed dramatically.

Avoid Offsets

Avoid large offsets in your data to prevent rounding errors. Consider the following example: Assumed your data set has a minimum to maximum range in <math>z</math> of 10 nano metre and the average value of your data is 10 metres, you need a precision of at least 10 digits to store this data with a resolution of 1 nano metre. This is already beyond the ability of single precision floating point data, that can only represent about seven decimal digits. But when you subtract an offset value of 10 metres from your data the absolute range becomes ±5 nano metres what can be stored with a precision of 7 digits in single precision floating point format. This results in an absolute precision of <math>10^{-15}</math> metres instead of <math>10^{-9}</math> metres.

To recover your offset you can store it in the Axis⇒Offset value in Record1. In generic it is a good idea to keep the offset for as many data manipulations as possible separated from your data.

Provide Meta Data

The meta data specified in Record2 are essential and some fields are even mandatory by the ISO5436-2 standard. Try to specify these information as complete as possible. If some data are not available such as a system serial number mark them clearly as unknown.

Keep in mind that good and complete meta data can dramatically increase the quality of your datasets! If you are not able to answer the following questions about a data set it may render completely useless:

• What has been measured?
• When has it been measured?
• Who did measure it (not mandatory)?
• What instrument type has been used to measure (contacting, non contacting)?
• Which specific machine has been used to perform the measurement?
• When was the system calibrated last time?