6 OpenCRG data format
6.1 Curved regular grids
A curved regular grid represents road surface data in proximity of an arbitrary road centerline. The road surface is tiled into a curved grid. Longitudinal cuts are parallel to the road centerline. Lateral cuts are orthogonal to the road centerline. One road data value is assigned to each tile. Road surface data usually represents road elevation but may also be used for other data, for example friction coefficients.
Curved regular grids use a reference line coordinate system. The road centerline is given by a curved reference line. A curved reference line is defined by series of low-precision heading angles. The u-direction follows the tangent of the reference line. The v-direction is orthogonal to the u-direction. Road surface data is given in z-direction orthogonal to the u/v-plane.
A curved regular grid may be placed in an inertial x/y-coordinate system by providing a high-precision start position in x/y-coordinates. To avoid drift when integrating along the reference line, an optional high-precision end position in x/y-coordinates may be provided. If such a position is provided, both forward integration and backward integration can be used for calculating the position of the reference line. The given start and end positions can be compared to the integration results to distribute errors along the reference line.
Figure 2 shows an example of an OpenCRG road surface description.
The reference line may be complemented by slope or banking (see Figure 3).
6.2 OpenCRG data files
OpenCRG data is stored in a compact hybrid file format. Its first part is a plain text header containing sections for road parameters, data channel definitions, and further optional sections. The second part contains the data payload in plain text or binary representation.
The plain text header shall consist of records with a maximum length of 72 ASCII characters. Any characters beyond the maximum length of 72 bytes shall be ignored. All records shall be terminated by LF or CRLF.
Use of character sets beyond ASCII is limited to comments in the plain text header. Using 8bit character sets like ISO 8859-1 or variable byte length character sets like UTF-8 may be possible, but the maximum record length shall be 72 bytes. Any use of non-ASCII characters is strongly discouraged, since the representation of the non-ASCII characters may fail in non-consistent environments.
All keywords used for sections or parameters inside the sections shall follow the rules of a simple variable naming convention: first character is a letter A-Z, next characters are letters A-Z, digits 0-9 and underscores _. The maximum keyword length is 31 characters. All keyword letters are treated case-insensitive.
Each plain text header section shall start with a line containing a `= OpenCRG data files
OpenCRG data is stored in a compact hybrid file format. Its first part is a plain text header containing sections for road parameters, data channel definitions, and further optional sections. The second part contains the data payload in plain text or binary representation.
The plain text header shall consist of records with a maximum length of 72 ASCII characters. Any characters beyond the maximum length of 72 bytes shall be ignored. All records shall be terminated by LF or CRLF.
Use of character sets beyond ASCII is limited to comments in the plain text header. Using 8bit character sets like ISO 8859-1 or variable byte length character sets like UTF-8 may be possible, but the maximum record length shall be 72 bytes. Any use of non-ASCII characters is strongly discouraged, since the representation of the non-ASCII characters may fail in non-consistent environments.
All keywords used for sections or parameters inside the sections shall follow the rules of a simple variable naming convention: first character is a letter A-Z, next characters are letters A-Z, digits 0-9 and underscores _. The maximum keyword length is 31 characters. All keyword letters are treated case-insensitive.
character as first character followed by a keyword. Each plain text header section shall be terminated by a new line with a single `= OpenCRG data files
OpenCRG data is stored in a compact hybrid file format. Its first part is a plain text header containing sections for road parameters, data channel definitions, and further optional sections. The second part contains the data payload in plain text or binary representation.
The plain text header shall consist of records with a maximum length of 72 ASCII characters. Any characters beyond the maximum length of 72 bytes shall be ignored. All records shall be terminated by LF or CRLF.
Use of character sets beyond ASCII is limited to comments in the plain text header. Using 8bit character sets like ISO 8859-1 or variable byte length character sets like UTF-8 may be possible, but the maximum record length shall be 72 bytes. Any use of non-ASCII characters is strongly discouraged, since the representation of the non-ASCII characters may fail in non-consistent environments.
All keywords used for sections or parameters inside the sections shall follow the rules of a simple variable naming convention: first character is a letter A-Z, next characters are letters A-Z, digits 0-9 and underscores _. The maximum keyword length is 31 characters. All keyword letters are treated case-insensitive.
character as first character. The keyword at the beginning of a data section and the closing `= OpenCRG data files
OpenCRG data is stored in a compact hybrid file format. Its first part is a plain text header containing sections for road parameters, data channel definitions, and further optional sections. The second part contains the data payload in plain text or binary representation.
The plain text header shall consist of records with a maximum length of 72 ASCII characters. Any characters beyond the maximum length of 72 bytes shall be ignored. All records shall be terminated by LF or CRLF.
Use of character sets beyond ASCII is limited to comments in the plain text header. Using 8bit character sets like ISO 8859-1 or variable byte length character sets like UTF-8 may be possible, but the maximum record length shall be 72 bytes. Any use of non-ASCII characters is strongly discouraged, since the representation of the non-ASCII characters may fail in non-consistent environments.
All keywords used for sections or parameters inside the sections shall follow the rules of a simple variable naming convention: first character is a letter A-Z, next characters are letters A-Z, digits 0-9 and underscores _. The maximum keyword length is 31 characters. All keyword letters are treated case-insensitive.
character at the end of a data section may be followed by inline comments.
Sections labeled by keywords shall be unique inside the plain text header. Parameters labeled by keywords shall be unique inside a section of the plain text header. The order of the sections in the plain text header and the order of parameters within the sections can be arranged in a flexible manner. To increase readability, the clear text header sections may appear in the sequence recommended in Table 4 and later paragraphs and samples.
The plain text header shall be terminated by a new line with double or multiple `= OpenCRG data files
OpenCRG data is stored in a compact hybrid file format. Its first part is a plain text header containing sections for road parameters, data channel definitions, and further optional sections. The second part contains the data payload in plain text or binary representation.
The plain text header shall consist of records with a maximum length of 72 ASCII characters. Any characters beyond the maximum length of 72 bytes shall be ignored. All records shall be terminated by LF or CRLF.
Use of character sets beyond ASCII is limited to comments in the plain text header. Using 8bit character sets like ISO 8859-1 or variable byte length character sets like UTF-8 may be possible, but the maximum record length shall be 72 bytes. Any use of non-ASCII characters is strongly discouraged, since the representation of the non-ASCII characters may fail in non-consistent environments.
All keywords used for sections or parameters inside the sections shall follow the rules of a simple variable naming convention: first character is a letter A-Z, next characters are letters A-Z, digits 0-9 and underscores _. The maximum keyword length is 31 characters. All keyword letters are treated case-insensitive.
Each plain text header section shall start with a line containing a `= OpenCRG data files
OpenCRG data is stored in a compact hybrid file format. Its first part is a plain text header containing sections for road parameters, data channel definitions, and further optional sections. The second part contains the data payload in plain text or binary representation.
The plain text header shall consist of records with a maximum length of 72 ASCII characters. Any characters beyond the maximum length of 72 bytes shall be ignored. All records shall be terminated by LF or CRLF.
Use of character sets beyond ASCII is limited to comments in the plain text header. Using 8bit character sets like ISO 8859-1 or variable byte length character sets like UTF-8 may be possible, but the maximum record length shall be 72 bytes. Any use of non-ASCII characters is strongly discouraged, since the representation of the non-ASCII characters may fail in non-consistent environments.
All keywords used for sections or parameters inside the sections shall follow the rules of a simple variable naming convention: first character is a letter A-Z, next characters are letters A-Z, digits 0-9 and underscores _. The maximum keyword length is 31 characters. All keyword letters are treated case-insensitive.
character as first character followed by a keyword. Each plain text header section shall be terminated by a new line with a single `= OpenCRG data files
OpenCRG data is stored in a compact hybrid file format. Its first part is a plain text header containing sections for road parameters, data channel definitions, and further optional sections. The second part contains the data payload in plain text or binary representation.
The plain text header shall consist of records with a maximum length of 72 ASCII characters. Any characters beyond the maximum length of 72 bytes shall be ignored. All records shall be terminated by LF or CRLF.
Use of character sets beyond ASCII is limited to comments in the plain text header. Using 8bit character sets like ISO 8859-1 or variable byte length character sets like UTF-8 may be possible, but the maximum record length shall be 72 bytes. Any use of non-ASCII characters is strongly discouraged, since the representation of the non-ASCII characters may fail in non-consistent environments.
All keywords used for sections or parameters inside the sections shall follow the rules of a simple variable naming convention: first character is a letter A-Z, next characters are letters A-Z, digits 0-9 and underscores _. The maximum keyword length is 31 characters. All keyword letters are treated case-insensitive.
character as first character. The keyword at the beginning of a data section and the closing `= OpenCRG data files
OpenCRG data is stored in a compact hybrid file format. Its first part is a plain text header containing sections for road parameters, data channel definitions, and further optional sections. The second part contains the data payload in plain text or binary representation.
The plain text header shall consist of records with a maximum length of 72 ASCII characters. Any characters beyond the maximum length of 72 bytes shall be ignored. All records shall be terminated by LF or CRLF.
Use of character sets beyond ASCII is limited to comments in the plain text header. Using 8bit character sets like ISO 8859-1 or variable byte length character sets like UTF-8 may be possible, but the maximum record length shall be 72 bytes. Any use of non-ASCII characters is strongly discouraged, since the representation of the non-ASCII characters may fail in non-consistent environments.
All keywords used for sections or parameters inside the sections shall follow the rules of a simple variable naming convention: first character is a letter A-Z, next characters are letters A-Z, digits 0-9 and underscores _. The maximum keyword length is 31 characters. All keyword letters are treated case-insensitive.
character at the end of a data section may be followed by inline comments.
Sections labeled by keywords shall be unique inside the plain text header. Parameters labeled by keywords shall be unique inside a section of the plain text header. The order of the sections in the plain text header and the order of parameters within the sections can be arranged in a flexible manner. To increase readability, the clear text header sections may appear in the sequence recommended in Table 4 and later paragraphs and samples.
as first characters and may be followed by an inline comment. This separator record shall be terminated by LF or CRLF.
The data payload shall consist of clear text records with a maximum length of 80 ASCII characters, terminated by LF or CRLF, or it shall consist of binary records of 80 bytes length without any extra terminators.
| Data section | Keyword | Content | Remark |
|---|---|---|---|
Header information |
|
Unstructured description in plain-text |
Mandatory |
Road parameter |
|
Structured definition of reference line in plain text |
Mandatory if file contains a road data section. |
Map projection data |
|
Structured definition of data for mapping OpenCRG data to geographic positions |
Optional |
Data definition |
|
Structured definition of data channels in plain text |
Mandatory if file contains a road data section. |
Options |
|
Structured definition of evaluation options in plain text |
Optional |
Modifiers |
|
Structured definition of data set modifiers in plain text |
Optional |
File reference |
|
References to other OpenCRG files in plain text |
Optional |
Road data |
none |
Actual road surface data in plain text or binary format. |
Optional |
6.3 Comments
An OpenCRG file may contain comments with further information about the file. These comments shall not substitute the introductory header information.
There are two types of comments in an OpenCRG file:
- Block comment
-
An asterisk (
*) at the beginning of a line causes the entire line to be treated as a comment. - Inline comment
-
An exclamation mark (
!) causes all following characters in this line to be treated as a comment.
6.4 Data sections
6.4.1 Header information
The header information section provides information about the file as human-readable text. For example, a header information section may contain:
-
Title of the file
-
Short description of the contents and purpose of the file
-
Information about creators or issuing organization
-
Copyright information
6.4.1.3 Rules
-
An OpenCRG data file shall contain a header information section.
-
The header information section shall be the first section in an OpenCRG data file.
-
The header information section should give information about the content of the file.
6.4.1.4 Examples
$CT
CRG file example for road surface description (width: 3m, length: 22m)
with curved reference line and grid of (0.25m...1.0m) x 1.0m.
A minimalist file can have an empty $CT, a minimalist $ROAD_CRG block,
and no comments marked by asterisk "*" in column 1 or marked by "!" in
other columns. So this file is completely equivalent to its commented
version in handmade_curved.crg .
Copyright 2005-2009 OpenCRG - Daimler AG - Jochen Rauh
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
More Information on OpenCRG open file formats and tools can be found at
http://www.opencrg.org
$!*********************************************************************
6.4.2 Road parameters
The road parameters section contains information about the reference line necessary for road reconstruction. With OpenCRG, road data is recorded in relation to the reference line. If an OpenCRG file contains a road data section, a road parameters section is therefore mandatory.
The minimum information necessary for creating a reference line is the distance between lateral cross sections. The REFERENCE_LINE_INCREMENT parameter is therefore mandatory. All other parameters are optional.
Curved regular grids may be placed in an inertial x/y-coordinate system and additionally in World Geodetic System WGS 84 by providing start positions or end positions in the respective coordinate system. The geodetic coordinates are purely informative and not suitable for exact geo-referencing.
Integration along the reference line can lead to error accumulation due to low-precision heading angles. To allow the detection and handling of integration errors, high-precision start positions and end positions in x/y-coordinates are necessary. Applications can then compare the integration result to the given positions.
6.4.2.2 Contents
The road parameters section contains parameters as key-value pairs.
| Parameter | Values | Description |
|---|---|---|
|
Double-precision floating-point number (default: 0.0) |
u-coordinate of start position. |
|
Double-precision floating-point number (default: calculated from road data) |
u-coordinate of end position. |
|
Double-precision floating-point number (default: none) |
Distance between lateral cross sections. |
|
Double-precision floating-point number (default: calculated from road data) |
v-coordinate of the outer right border of the road. |
|
Double-precision floating-point number (default: calculated from road data) |
v-coordinate of the outer left border of the road. |
|
Double-precision floating-point number (default: calculated from road data) |
Distance between axial cross sections. |
|
Double-precision floating-point number (default: 0.0) |
Slope at start position. |
|
Double-precision floating-point number (default: 0.0) |
Slope at end position. |
|
Double-precision floating-point number (default: 0.0) |
Banking at start position. |
|
Double-precision floating-point number (default: 0.0) |
Banking at end position. |
|
Double-precision floating-point number (default: 0.0) |
x-coordinate of start position of the reference line. |
|
Double-precision floating-point number (default: 0.0) |
y-coordinate of start position of the reference line. |
|
Double-precision floating-point number (default: calculated from road data) |
x-coordinate of end position of the reference line. |
|
Double-precision floating-point number (default: calculated from road data) |
y-coordinate of end position of the reference line. |
|
Double-precision floating-point number (default: 0.0) |
Global offset for x-coordinates. |
|
Double-precision floating-point number (default: 0.0) |
Global offset for y-coordinates. |
|
Double-precision floating-point number (default: 0.0) |
Heading angle at start position. |
|
Double-precision floating-point number (default: 0.0) |
Heading angle at end position. |
|
Double-precision floating-point number (default: 0.0) |
Global offset for heading angle. |
|
Double-precision floating-point number (default: 0.0) |
Elevation at start position. |
|
Double-precision floating-point number (default: 0.0) |
Elevation at end position. |
|
Double-precision floating-point number (default: 0.0) |
Global offset for elevation. |
|
Double-precision floating-point number |
Longitude of the start position in WGS 84 coordinates. |
|
Double-precision floating-point number |
Latitude of start position in WGS 84 coordinates. |
|
Double-precision floating-point number |
Longitude of end position in WGS 84 coordinates. |
|
Double-precision floating-point number |
Latitude of end position in WGS 84 coordinates. |
|
Double-precision floating-point number |
Altitude of start position in WGS 84 coordinates. |
|
Double-precision floating-point number |
Altitude of end position in WGS 84 coordinates. |
6.4.2.3 Rules
-
If an OpenCRG file contains a road data section, the file shall also contain a road parameters section.
-
Parameters in the road parameters section shall be provided as key-value pairs using the syntax
PARAMETER = value. -
A road parameters section shall define REFERENCE_LINE_INCREMENT.
-
A road parameters section should define x/y-coordinates of both start position and end position to handle numeric errors in road reconstruction.
-
A road parameters section may define WGS 84 coordinates of the start position and end position if available. These coordinates shall not be used for geo-referencing.
6.4.2.4 Examples
The following road parameters section defines a 3 m wide road with 45 data points along the reference line. The start of the reference line coincides with the origin of the x/y-coordinate system.
$ROAD_CRG REFERENCE_LINE_START_U = 0.0 REFERENCE_LINE_END_U = 22.0 REFERENCE_LINE_INCREMENT = 0.5 REFERENCE_LINE_START_X = 0.0 REFERENCE_LINE_START_Y = 0.0 LONG_SECTION_V_RIGHT =-1.50 LONG_SECTION_V_LEFT = 1.50 $!********************************
6.4.3 Map projection data
The map projection data section contains information necessary for mapping road data to geographic positions. The map projection data section is optional.
A map projection data section shall at least specify a map projection, either by providing the name of the projection or the projection parameters themselves.
If geodetic coordinates use a global ellipsoid other than WGS 84, the ellipsoid shall be specified, either by providing the name of the ellipsoid or the semi-major and the semi-minor axis in case of a user-defined ellipsoid.
A map projection can involve a datum transformation, for example with Gauss-Krüger projections of WGS 84 coordinates. In this case, both a local ellipsoid and a transformation type including all 7 parameters shall be specified.
The map projection parameters PROJ_* are relevant for the generic transverse Mercator projection (PROJ_NM = TM or PROJ_NM = TM_*). If the generic transverse Mercator projection is used with a zone substring PROJ_L0 is ignored.
6.4.3.2 Contents
| Parameter | Values | Description |
|---|---|---|
|
Double-precision floating-point number (default: 0.0) |
Semi-major axis of user-defined global ellipsoid. |
|
Double-precision floating-point number (default: gell_a) |
Semi-minor axis of user-defined global ellipsoid. |
|
|
Identifier of the global ellipsoid. |
|
|
Identifier of datum transformation type.
|
|
Double-precision floating-point number (default: 0.0) |
Helmert transformation parameter: scalar scaling factor minus one ( |
|
Double-precision floating-point number (default: 0.0) |
Helmert transformation parameter: rotation around the x-axis. |
|
Double-precision floating-point number (default: 0.0) |
Helmert transformation parameter: rotation around the y-axis. |
|
Double-precision floating-point number (default: 0.0) |
Helmert transformation parameter: rotation around the z-axis. |
|
Double-precision floating-point number (default: 0.0) |
Helmert transformation parameter: translation along the x-axis. |
|
Double-precision floating-point number (default: 0.0) |
Helmert transformation parameter: translation along the y-axis. |
|
Double-precision floating-point number (default: 0.0) |
Helmert transformation parameter: translation along the z-axis. |
|
Double-precision floating-point number (default: 0.0) |
Semi-major axis of the local ellipsoid. |
|
Double-precision floating-point number (default: lell_a) |
Semi-minor axis of the local ellipsoid. |
|
|
Identifier of the local ellipsoid. |
|
GK3_0 … GK3_119, GK6_0 … GK6_59, UTM_01C … UTM_60X, TM_0 … TM_359, TM |
Identifier of the map projection
|
|
Double-precision floating-point number (default: 1.0) |
Map projection parameter: center meridian scaling. |
|
Double-precision floating-point number (default: 0.0) |
Map projection parameter: latitude of origin. |
|
Double-precision floating-point number (default: 0.0) |
Map projection parameter: longitude of origin. |
|
Double-precision floating-point number (default: 0.0) |
Map projection parameter: false easting. |
|
Double-precision floating-point number (default: 0.0) |
Map projection parameter: false northing. |
6.4.3.3 Rules
-
Parameters in a map projection data section shall be provided as key-value pairs using the syntax
PARAMETER = value. -
The map projection data section shall contain enough information to execute the desired transformation.
-
For UTM, defining the zone number and band letter shall be sufficient.
6.4.4 Data definition
The data definition section defines the format and sequence of data in the following road data section. If an OpenCRG file contains a road data section, a data definition section is therefore mandatory.
Lines starting with #: define the data format used. OpenCRG supports the following formats:
-
LRFI (long, real, formatted, interchangeable)
-
LDFI (long, double, formatted, interchangeable)
-
KRBI (kernel, real, binary, interchangeable)
-
KDBI (kernel, double, binary, interchangeable)
If no data format is defined, road data is considered to use KRBI format.
Lines starting with D: define a channel in the road data section. A channel definition describes both the type of data and the unit. A channel corresponds to a column in the road data section. Channel definitions appear in the same sequence as the corresponding columns appear in the road data section.
Lines starting with U: define a virtual channel. A virtual channel does not contain original data. Instead, data in a virtual channel is derived from data and definitions provided elsewhere in the file. Virtual channels may safely be ignored.
6.4.4.2 Contents
| Definition | Description |
|---|---|
|
Binary data format using numbers of type real |
|
Binary data format using numbers of type double |
|
Human-readable plain-text format using numbers of type real |
|
Human-readable plain-text format using numbers of type double |
|
Data entries represent heading angles of the reference line in rad. |
|
Data entries represent banking as dimensionless fraction. |
|
Data entries represent slope as dimensionless fraction. |
|
Data entries represent a longitudinal cut at position X in meters. X corresponds to a v-coordinate. |
|
Data entries represent the X-th longitudinal cut. To use this definition, both the width of the road and the increments in v-direction must be defined in the road parameters section. |
6.4.4.3 Rules
-
If an OpenCRG file contains a road data section, the file shall also contain a data definition section.
-
The data definition section should define the data format used.
-
The data definition section shall define all channels of the road data section.
-
Channel definitions shall appear in the same sequence as the corresponding columns in the road data section.
-
The data definition section may define a virtual channel.
6.4.4.4 Examples
The following data definition section defines ten channels. Each channel corresponds to a column in the road data section. The first three columns contain reference line data. The other seven columns contain road surface data. The v-positions of the longitudinal cuts are defined explicitly.
$KD_DEFINiTION #:LRFI ! plain-text data, numbers of type real D:reference line phi,rad ! heading angle D:reference line banking,m/m ! lateral banking (cross slope) D:reference line slope,m/m ! longitudinal slope D:long section at v = -1.500,m ! 1.50 m right of reference line D:long section at v = -1.250,m ! 1.25 m right of reference line D:long section at v = -1.000,m ! 1.00 m right of reference line D:long section at v = 0.000,m ! on reference line D:long section at v = 1.000,m ! 1.00 m left of reference line D:long section at v = 1.250,m ! 1.25 m left of reference line D:long section at v = 1.500,m ! 1.50 m left of reference line $!********************************
The following examples illustrates how the data definition section interacts with the road parameters section. In the example, the road parameters section defines a 3 m wide road with longitudinal cuts every 0.1 m. The channel definitions only refer to the number of the cut without explicitly stating the v-position.
$ROAD_CRG ! road parameters section REFERENCE_LINE_INCREMENT = 0.01 ! 1 cm between every lateral cut LONG_SECTION_V_RIGHT = -1.50 ! right road border LONG_SECTION_V_RIGHT = 1.50 ! left road border LONG_SECTION_V_INCREMENT = 0.10 ! 10 cm between every longitudinal cut $!******************************** $KD_DEFINiTION ! data definition section #:KRBI ! binary data, numbers of type real D:reference line phi,rad ! heading angle D:long section 1,m ! 1.50 m right of reference line D:long section 2,m ! 1.40 m right of reference line ... D:long section 16,m ! on reference line ... D:long section 30,m ! 1.40 m left of reference line D:long section 31,m ! 1.50 m left of reference line $!********************************
6.4.5 Options
The optional options section defines values for options. Options influence the evaluation of OpenCRG data. They do not modify the road data itself.
A creator of an OpenCRG file must not rely on applications evaluating the data with options set to the values specified in the OpenCRG file. Applications shall define default values for options. Applications may use options provided in an OpenCRG file to override these default values. A creator of an OpenCRG file may thus use the options section to express the intended option settings.
An OpenCRG file may specify options without having a section containing road data. Such a file may be referenced in another OpenCRG file, which contains the road data, and be used as a control file.
Border mode options and border offset options influence the returned z-values when the u/v-coordinates in a query exceed the defined road in the respective direction. These options may be used to mark borders, provide fallback values, or to extend the data beyond the defined area.
Border-smoothing options provide a linear ascend or descend of z-values along a defined range at the beginning and the end of the road. These options can be used to smooth abrupt changes in road data at the beginning or the end of the road, for example, in order to reduce unwanted high-frequency input in vibration simulation.
When the u-coordinate exceeds the defined range, the corresponding x/y-coordinates are calculated by either extrapolating the reference line or evaluating the reference line as closed track. The reference-line-continuation option defines whether the reference line is extrapolated or treated as closed track. A track can be closed, if the extrapolated tracks intersect at an angle of less than 60 degree.
6.4.5.2 Contents
The options section contains options provided as key-value pairs.
| Option | Values | Description |
|---|---|---|
|
0, 1, 2, 3, 4 (default: 2) |
Returned z-value, when a query exceeds the beginning or the end of the road.
|
|
0, 1, 2, 3, 4 (default: 2) |
Returned z-value, when a query exceeds the left side or the right side of the road.
|
|
Double-precision floating-point number (default: 0.0) |
Offset for returned z-value, when a query exceeds the beginning or the end of the road. |
|
Double-precision floating-point number (default: 0.0) |
Offset for returned z-value, when a query exceeds the left side or the right side of the road. |
|
Double-precision floating-point number from 0.0 to umax (default: 0.0) |
Range for scaling z-values linearly from 0 to the actual value, including slope and banking. Provides a smooth increase of road data at the beginning of the road. |
|
Double-precision floating-point number from 0.0 to umax (default: 0.0) |
Range for scaling z-values linearly from the actual value to 0. Provides a smooth decrease of road data at the end of the road. |
|
0, 1 (default: 0) |
Mode for computing x/y-positions if a given u-coordinate is positioned outside the defined reference line.
|
|
-1, 0, [1;∞[ (default: -1) |
Number of warning messages displayed.
|
|
0, 1 (default: 0) |
Check whether local curvature limit is exceeded.
|
|
0, 1 (default: 1) |
Check whether global curvature limit is exceeded.
|
|
[1e-6; 1e-2] (default: 1e-6) |
Expected minimal accuracy, used for numerical consistency checks. |
|
less than 0.001*(1-CHECK_EPS) or abs(round(CHECK_INC=0.001 * (1-CHECK_EPS)) 0.001 * (1-CHECK_EPS) * CHECK_INC) > CHECK_EPS * max(0.001 * (1-CHECK_EPS); CHECK_INC) (default: 1e-3) |
Expected minimum increment, used for numerical consistency checks. |
|
[CHECK_EPS*CHECK_INC; 0.5*CHECK_INC] (default: 0.1*CHECK_INC) |
Expected absolute tolerance, used for numerical consistency checks. |
|
[0.1*CHECK_INC; 1] (default: 5e-3) |
Expected projection tolerance, used for numerical consistency checks. |
|
[0.1*CHECK_INC; 1000] (default: 10) |
Expected WGS 84 tolerance, used for numerical consistency checks. |
6.4.5.3 Rules
-
An OpenCRG file may contain an options section.
-
Options in an options section shall be provided as key-value pairs using the syntax
OPTION = value. -
An options section may be empty.
-
If the data in an OpenCRG file is intended to be evaluated with options set to specific values, these values should be specified in the OpenCRG file.
-
Applications shall define default values for options. Options defined in an OpenCRG file may override these default values.
6.4.5.4 Examples
The following example illustrates how to create an endless road using a border mode option. The border smoothing prevents unnecessary steep changes at the beginning and the end of the road.
$ROAD_CRG_OPTS
BORDER_MODE_U = 3 ! return 0 when query exceeds the beginning or
! end of the road
BORDER_SMOOTH_UBEG = 0.5 ! over the first 2 m, increase z-values linearly
! from 0 to the actual value
BORDER_SMOOTH_UEND = 0.5 ! over the last 2 m, decrease z-values linearly
! from 0 to the actual value
$!*********************
6.4.6 Modifiers
The optional modifiers section defines values for modifiers. Modifiers alter OpenCRG data stored in memory.
Applications may define default values for modifiers. However, if an OpenCRG file contains a modifiers section, applications must remove all default modifier values. Instead, only the modifiers specified in the OpenCRG file shall be applied. If an OpenCRG file contains an empty modifiers sections, no modifiers are applied to the data. Applications may nonetheless apply different modifiers explicitly via API calls.
An OpenCRG file may specify modifiers without having a section containing actual road data. Such a file may be used as a control file by referencing it in another OpenCRG file containing the actual data.
An OpenCRG data set can be re-located by mapping a reference point in u/v-coordinates to a new target position in x/y-coordinates.
-
The reference point may be explicitly defined in u/v-coordinates.
-
Alternatively, the reference point may be defined as fractions of the data-set extent in u-direction or v-direction.
-
Additionally, the reference point may be modified by adding an offset.
The methods for defining a reference point may be combined as long as this combination does not result in contradicting definitions. The target position of the data set is defined in x/y-coordinates and with an absolute heading angle.
An OpenCRG data set may be relocated by rotating and shifting the data set in x/y-coordinates. First, the data set is rotated by a rotation angle around a rotation center. Then the data set is translated in x-direction, y-direction and z-direction.
OpenCRG data may be scaled in multiple ways. Scaling factors may be applied to length, width, z-values, slope and banking. If a factor of 0 is specified for elevation data, that modifier is ignored. For length and width, only factors greater than 0 are valid.
The curvature of the reference line may be scaled by a factor, resulting in a different end point. Scaling the curvature by a factor of 0 results in a straight line.
When preparing a data set for evaluation, the borders of the road in v-direction are checked for NaN values. These NaN values may be kept or replaced by defined values. If NaN values are to be kept, the BORDER_MODE_V option shall be set to 0 (none). If NaN values are to be replaced, an additional offset may be applied to them.
6.4.6.2 Contents
The modifiers section contains modifiers provided as key-value pairs.
| Modifier | Values | Description |
|---|---|---|
|
Double-precision floating-point number |
u-coordinate of reference point for relocating by reference point. |
|
Double-precision floating-point number |
v-coordinate of reference point for relocating by reference point. |
|
Double-precision floating-point number: [0.0, 1.0] (default: 0.0) |
Relative u-coordinate of reference point for relocating by reference point. |
|
Double-precision floating-point number (default: 0.0) |
Offset for u-coordinate of reference point for relocating by reference point. |
|
Double-precision floating-point number: [0.0, 1.0] (default: 0.0) |
Relative v-coordinate of reference point for relocating by reference point. |
|
Double-precision floating-point number (default: 0.0) |
Offset for v-coordinate of reference point for relocating by reference point. |
|
Double-precision floating-point number (default: 0.0) |
x-coordinate of target position for relocating by reference point. |
|
Double-precision floating-point number (default: 0.0) |
y-coordinate of target position for relocating by reference point. |
|
Double-precision floating-point number (default: 0.0) |
z-coordinate of target position for relocating by reference point. |
|
Double-precision floating-point number (default: 0.0) |
Absolute heading angle of target position for relocating by reference point. |
|
Double-precision floating-point number (default: x-coordinate of starting position) |
x-coordinate of rotation center for relocating by rotation and translation. |
|
Double-precision floating-point number (default: y-coordinate of starting position) |
y-coordinate of rotation center for relocating by rotation and translation. |
|
Double-precision floating-point number (default: 0.0) |
Rotation angle for re-locating by rotation and translation. |
|
Double-precision floating-point number (default: 0.0) |
Offset in x-direction for relocating by rotation and translation. |
|
Double-precision floating-point number (default: 0.0) |
Offset in y-direction for relocating by rotation and translation. |
|
Double-precision floating-point number (default: 0.0) |
Offset in z-direction for relocating by rotation and translation. |
|
Double-precision floating-point number (default: 0.0) |
Factor for scaling the data in z-direction. |
|
Double-precision floating-point number (default: 0.0) |
Factor for scaling slope in elevation data. |
|
Double-precision floating-point number (default: 0.0) |
Factor for scaling banking in elevation data. |
|
Double-precision floating-point number: ]0.0,∞] (default: 0.0) |
Factor for scaling the data in u-direction. |
|
Double-precision floating-point number: ]0.0,∞] (default: 0.0) |
Factor for scaling the data in v-direction. |
|
Double-precision floating-point number: : [0.0,∞] (default: 0.0) |
Factor for scaling the curvature. |
|
0, 1, 2 |
Mode for replacing NaN values in road data borders.
|
|
Double-precision floating-point number (default: 0.0) |
Offset applied to replaced NaN values. |
6.4.6.3 Rules
-
An OpenCRG file may contain a modifiers section.
-
Modifiers in a modifiers section shall be provided as key-value pairs using the syntax
MODIFIER = value. -
A modifiers section may be empty.
-
If the data in an OpenCRG file is intended to be used with specific modifiers applied, these modifiers should be defined in the OpenCRG file.
-
If an OpenCRG file contains a modifiers section, an application must ignore its own default modifier values and must apply only the modifiers specified in the OpenCRG file.
6.4.6.4 Examples
In the following example, the reference line is first rotated by 1.57 rad (90°) around the origin of the x/y-coordinate system and then shifted by 100 m in x-direction, y-direction and z-direction.
$ROAD_CRG_MODS REFLINE_ROTCENTER_X = 0 ! rotation center at x = 0 REFLINE_ROTCENTER_Y = 0 ! rotation center at y = 0 REFLINE_OFFSET_PHI = 1.57 ! rotated by 1.57 rad (90°) REFLINE_OFFSET_Z = 100 ! shift 100 m in x-direction REFLINE_OFFSET_Y = 100 ! shift 100 m in y-direction REFLINE_OFFSET_Z = 100 ! shift 100 m in z-direction $!************************
The following example illustrates how NaN values at the border can be replaced by an arbitrary value (here: 10 m).
$ROAD_CRG_MODS GRID_NAN_MODE = 1 ! replace NaN with z = 0 GRID_NAN_OFFSET = 10 ! offset former NaN values by 10 m $!************************
6.4.7 File reference
The optional file reference section of a first OpenCRG file references a second OpenCRG file.
A first (incomplete) OpenCRG file with the file reference section can be used to replace options and modifiers of a second (full) OpenCRG file containing actual road data.
Any empty or non-empty option or modifier section in the first OpenCRG file replaces the equivalent section in the second OpenCRG file. Any missing option or modifier section in the first OpenCRG file enables the use of the equivalent section (or it’s defaults) in the second OpenCRG file. Any further sections and actual road data in the first OpenCRG file are ignored.
6.4.7.2 Contents
File references use the following symbols for describing paths.
| Symbol | Function |
|---|---|
/ |
Path delimiter. |
. |
Current directory. |
.. |
Superordinate directory. |
$ |
Reference to environment variable. |
6.4.7.3 Rules
-
An OpenCRG file may contain a file reference section.
-
A file reference section may contain a single file reference.
-
File references may use absolute or relative paths.
-
File references may use environment variables.
-
A path may be split into several lines. These lines shall not contain leading or trailing spaces, tabs, asterisks, and exclamation marks.
6.4.7.4 Examples
/home/name/crg-files/handmade_straight.crg
/home/name/crg-files/hand made_straight.crg
./handmade_straight.crg
$crgpath/handmade_straight.crg
$ROAD_CRG_FILE /home/name/crg-files/road_data.crg $!********
6.4.8 Road data
The road data section contains the actual road surface data. Road surface data is not limited to road elevation, although this is the primary use case. For example, an OpenCRG file may contain friction coefficients or color values.
Road data is stored as low-precision array as defined in the data definition section. Columns are longitudinal cuts parallel to the reference line. Rows are lateral cuts orthogonal to the reference line. Additional columns may contain reference line data, for example, heading angle, banking or slope.
A single record shall contain a maximum of 80 byte. If the defined data channels exceed this limit, the respective data row shall be wrapped to the next record. In plain-text format, each data row shall start in a new record. In binary format, records are successively filled up to 80 byte. The last record is padded with NaNs.
6.4.8.1 Contents
In plain-text formats, numbers are represented as follows:
-
Numbers of type real are 10 characters long for a maximum of 8 numbers per record.
-
Numbers of type double are 20 characters long for a maximum of 4 numbers per record.
-
Numbers shall be represented using fixpoint or scientific format.
-
NaNs are represented by a placeholder with a leading asterisk (
*).
In binary formats, numbers are represented as follows:
-
Numbers shall be represented using IEEE Big Endian format.
-
Numbers of type real are 4 byte long for a maximum of 20 numbers per record.
-
Numbers of type double are 8 byte long for a maximum of 10 numbers per record.
-
NaNs are represented according to IEEE 754.
6.4.8.3 Rules
-
An OpenCRG file may contain a road data section.
-
The road data section shall be the last section of an OpenCRG file.
-
Data formatting shall match the definitions in the data definition section.
-
The road data section may contain other data than elevation.
-
The road data may contain NaN values, but there must be at least one valid (non-NaN) value per cross section (lateral profile at a given u-position).
-
NaN values must not occur between non-NaN values within a cross section (lateral profile at a given u-position). This means NaN values can only appear from the left and/or the right border of the actual road data.
6.4.8.4 Examples
The example shows road data for a 1 m wide road. The road data is organized in a 4-by-10 matrix. The first column contains heading angles of the reference line, ignoring the first value, starting with the second value to describe the direction from the first to the second reference point. The following three columns contain actual road surface data. One value on the right border of the road is undefined (NaN).
$ROAD_CRG ! road parameters section REFERENCE_LINE_INCREMENT = 0.50 ! 50 cm between every lateral cut LONG_SECTION_V_RIGHT = -0.50 ! right road border LONG_SECTION_V_RIGHT = 0.50 ! left road border LONG_SECTION_V_INCREMENT = 0.50 ! 50 cm between every longitudinal cut $!******10********20********30********40********50********60********70** $KD_DEFINiTION ! data definition section #:LRFI ! plain-text data, real numbers D:reference line phi,rad ! heading angle D:long section 1,m ! 0.50m right of reference line D:long section 2,m ! on reference line D:long section 3,m ! 0.50m left of reference line $!******10********20********30********40********50********60********70** * Sample payload data, 4 channels as defined by "D:" above: * heading l_sec 1 l_sec 2 l_sec 3 * angle v=-0.50 v= 0.00 v= 0.50 $!*****10********20********30********40********50********60********70********80 *missing* 0.0000000 0.0000000 0.0000000 0.0000000 0.0000000 0.0000000 0.0000000 -0.0110000 0.0000000 0.0000000 0.0000000 -0.0110000 0.0111111 0.0111111 0.0000000 0.0000000 0.0000000 0.0000000 0.0000000 0.0110000 *missing* 0.0000000 0.0111111 0.0220000-0.0111111 0.0111111 0.0222222 0.0330000-0.0111111 0.0222222 0.0333333 0.0440000-0.0111111 0.0111111 0.0222222 0.0550000-0.0000000 0.0000000 0.0111111
6.5 Sample OpenCRG files
The OpenCRG software package contains various sample files demonstrating different use cases.
Sample files with binary road data are stored in open-crg/crg-bin/ and comprise
the following:
belgian_block.crg-
Binary data set for complex tests.
Sample files with human-readable road data are stored in open-crg/crg-txt/ and comprise
the following:
fileref.crg-
Referencing another CRG file.
fileref_mods.crg-
Referencing another CRG file and modifiers.
fileref_opts.crg-
Referencing another CRG file and options.
handmade_arc.crg-
180° arc.
handmade_banked.crg-
Straight road with banking.
handmade_circle.crg-
Circular road.
handmade_curved.crg-
Curved road.
handmade_curved_banked_sloped.crg-
Curved road with banking and slope.
handmade_curved_minimalist.crg-
Minimal OpenCRG file.
handmade_platform.crg-
Level road with alternating height values.
handmade_sloped.crg-
Straight road with slope.
handmade_sloped_opts.crg-
Straight road with slope and options.
handmade_straight.crg-
Straight road (LRFI format).
handmade_straight_double.crg-
Straight road (LDRI format).
handmade_straight_minimalist.crg-
Minimal OpenCRG file.
handmade_vtest.crg-
Human-readable test relating to v-options.
testOptionBorderMode.crg-
Testing different border mode options.