1. Foreword

ASAM OpenCRG provides an exchange format for the description of static road surfaces. The format can be used by applications for tire simulation, vibration simulation and driving simulation. In addition to the data format for storing and exchanging road surface data, OpenCRG includes a tool suite for creating, modifying and evaluating OpenCRG data.

1.1. Deliverables of OpenCRG

The following deliverables are provided for OpenCRG:

User guide

The User Guides help to get started with the OpenCRG APIs and how OpenCRG can be applied

Sample OpenCRG files

These demo files are explanatory examples

C-API including demo files and test scripts

The C-API is capable of reading and evaluating OpenCRG Files

MATLAB library including demo files and test scripts

The Matlab API can create, manipulate, visualize and validate OpenCRG Files

2. Introduction

2.1. Overview

The ASAM OpenCRG format provides a common format for describing road surfaces. The data in an OpenCRG file usually describes road elevation. OpenCRG file can be used for both synthetic or real road surfaces. The main purpose of OpenCRG is to provide a road surface description that can be fed into simulations and to make these road surface descriptions exchangeable.

2.2. Motivation

OpenCRG comprises open file formats and open source tools for the detailed description, creation and evaluation of road surfaces. As basic functionality OpenCRG describes the geometry of the road surface based on a reference line and a height grid (which can also be used for other scalar data). It is intended for vehicle dynamics, tire, vibration and driving simulations. For these purposes the OpenCRG project provides the following features: ASCII and binary file formats with clear-text headers, an open source C-API for data handling and evaluation and open source MATLAB® API for data manipulation and generation and a library of sample data.

OpenCRG is to be understood as a complementary standard to OpenDRIVE. While OpenDRIVE files are describing road networks with respect to all data belonging to the road environment, OpenCRG describes the road surface in detail. OpenDRIVE allows the referencing to OpenCRG files.

2.3. Normative and non-normative statements and deliverables

This specification uses a standard information structure. The following rules apply regarding normativity of sections:

  • Statements expressed as requirements, permissions, or prohibitions according to the use of modal verbs, as defined in Modal verbs, are normative.

  • Keywords of OpenCRG data structures in "Keyword" sections are normative.

  • Content descriptions of OpenCRG data structures in "Contents" sections are normative.

  • Rules for OpenCRG data structures in "Rules" sections are normative.

  • The OpenCRG toolsuite and its use are non-normative.

  • Examples and use case descriptions are non-normative.

2.4. Conventions

2.4.1. Naming conventions

In this document, the following conventions apply:

data types are given according to IEEE 754 standard.

2.4.2. Units

Unless stated otherwise, all numeric values within this specification are in SI units, for example:

  • position/distance in [m]

  • angles in [rad]

Geographic positions are stated in the unit defined by the spatial coordinate system, for example, in accordance with WGS 84 – EPSG 4326.

2.4.3. Modal verbs

To ensure compliance with the OpenCRG standard, users must be able to distinguish between mandatory requirements, recommendations, permissions, as well as possibilities, capabilities, obligations and necessities.

The following rules for using modal verbs apply:

Table 1. Rules for using modal verbs
Provision Verbal form

Requirement
Requirements shall be followed strictly in order to be conform to the standard. Deviations are not allowed.

shall
shall not

Recommendation
Recommendations indicate that among several possibilities, one is recommended as particularly suitable, without mentioning or excluding others.

should
should not

Permission
Permissions indicate a course of action permissible within the limits of OpenCRG deliverables.

may
need not

Possibility and capability
These verbal forms are used for stating possibilities or capabilities, being technical, material, physical, or others.

can
can not

Obligation and necessity
These verbal forms are used to describe legal, organizational, or technical obligations and necessities that are not regulated or enforced by the OpenCRG standard.

must
must not

2.4.4. Typographic conventions

This documentation uses the following typographical conventions:

Table 2. Typographical conventions
Mark-up Definition

Code elements

This format is used for code elements, such as technical names of classes and attributes, as well as attribute values.

Code snippets

This format is used for excerpts of code that serve as an example for implementation.

Terms

This format is used to introduce glossary terms, new terms and to emphasize terms.

Mathematical elements

This format is used for calculations and mathematical elements.

2.4.5. Curvature

For curvature indications, the following convention applies:

  • Positive curvature: left curve (counter-clockwise motion)

  • Negative curvature: right curve (clockwise motion)

Curvature == 1/radius

3. Relations to other standards

3.1. Positioning of ASAM OpenCRG within ASAM activities

ASAM OpenCRG is part of the ASAM simulation standards that focus on simulation data for the automotive environment. Next to OpenCRG, ASAM provides other standards for the simulation domain, like ASAM OpenDRIVE and ASAM OpenSCENARIO.

3.2. Relation of ASAM OpenCRG to OpenDRIVE and OpenSCENARIO

ASAM OpenCRG defines a storage format for the static description of road surfaces. In combination with ASAM OpenDRIVE it is possible to add very detailed road surface descriptions to road networks. ASAM OpenDRIVE and ASAM OpenCRG only contain static content. To add dynamic content ASAM OpenSCENARIO is needed. When combined, all three standards provide a scenario-driven description of traffic simulation that contains static and dynamic content.

img1
Figure 1. Relation between OpenDRIVE, OpenCRG, and OpenSCENARIO

3.3. Backward compatibility to earlier releases

ASAM OpenCRG 1.2.0 is backward compatible to OpenCRG 1.1.2.

3.4. References to other standards

  • ISO 8855 for right handed coordinate systems

  • ISO 8601 for time / date

  • ISO 8859-1 for plain-text encoding

  • Georeferencing (ISO DIN 19111)

  • ASAM OpenDRIVE

  • ASAM OpenSCENARIO

  • IEEE 754

4. OpenCRG data format

4.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.

img2
Figure 2. OpenCRG road surface description using u/v-coordinates and x/y-coordinates.

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. OpenCRG road surface description using u/v-coordinates and x/y-coordinates. shows an example of an OpenCRG road surface description.

banking_slope
Figure 3. Schematic drawing of banking and slope.

The reference line may be complemented by slope or banking (see Schematic drawing of banking and slope.).

4.2. OpenCRG data files

An OpenCRG file consists of several data sections that represent different aspects of the road surface data described in that file. OpenCRG files are written in plain text using ISO 8859-1 encoding. The actual road data may be provided in a binary format. Each line in a data section is considered a record. Except for the road data section, a record shall have a maximum length of 72 byte for a maximum of 72 characters per record. In the road data section, a record shall have a maximum length of 80 byte.

Each data section shall start with a line containing a $ character followed by a keyword. Each data section shall be terminated by a new line with a $ character as first character. The keyword at the beginning of a data section and the closing $ character at the end of a data section may be followed by inline comments.

Every OpenCRG file shall start with a header information section, describing the contents of the file. If a road data section is present, it shall be the last section in the OpenCRG file. The sequence of the other data sections is not defined. To increase readability, data sections should appear in the sequence recommended in Overview of data sections in recommended sequence..

4.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.

4.4. Data sections

4.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

Keyword
$CT
Contents

The header information section contains unstructured plain text.

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.

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
$!*********************************************************************

4.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.

Keyword
$ROAD_CRG
Contents

The road parameters section contains parameters as key-value pairs.

Parameter Values Description

REFERENCE_LINE_START_U

Double-precision floating-point number (default: 0.0)

u-coordinate of start position.

REFERENCE_LINE_END_U

Double-precision floating-point number (default: calculated from road data)

u-coordinate of end position.

REFERENCE_LINE_INCREMENT

Double-precision floating-point number (default: none)

Distance between lateral cross sections.

LONG_SECTION_V_RIGHT

Double-precision floating-point number (default: calculated from road data)

v-coordinate of the outer right border of the road.

LONG_SECTION_V_LEFT

Double-precision floating-point number (default: calculated from road data)

v-coordinate of the outer left border of the road.

LONG_SECTION_V_INCREMENT

Double-precision floating-point number (default: calculated from road data)

Distance between axial cross sections.

REFERENCE_LINE_START_S

Double-precision floating-point number (default: 0.0)

Slope at start position.

REFERENCE_LINE_END_S

Double-precision floating-point number (default: 0.0)

Slope at end position.

REFERENCE_LINE_START_B

Double-precision floating-point number (default: 0.0)

Banking at start position.

REFERENCE_LINE_END_B

Double-precision floating-point number (default: 0.0)

Banking at end position.

REFERENCE_LINE_START_X

Double-precision floating-point number (default: 0.0)

x-coordinate of start position of the reference line.

REFERENCE_LINE_START_Y

Double-precision floating-point number (default: 0.0)

y-coordinate of start position of the reference line.

REFERENCE_LINE_END_X

Double-precision floating-point number (default: calculated from road data)

x-coordinate of end position of the reference line.

REFERENCE_LINE_END_Y

Double-precision floating-point number (default: calculated from road data)

y-coordinate of end position of the reference line.

REFERENCE_LINE_OFFSET_X

Double-precision floating-point number (default: 0.0)

Global offset for x-coordinates.

REFERENCE_LINE_OFFSET_Y

Double-precision floating-point number (default: 0.0)

Global offset for y-coordinates.

REFERENCE_LINE_START_PHI

Double-precision floating-point number (default: 0.0)

Heading angle at start position.

REFERENCE_LINE_END_PHI

Double-precision floating-point number (default: 0.0)

Heading angle at end position.

REFERENCE_LINE_OFFSET_PHI

Double-precision floating-point number (default: 0.0)

Global offset for heading angle.

REFERENCE_LINE_START_Z

Double-precision floating-point number (default: 0.0)

Elevation at start position.

REFERENCE_LINE_END_Z

Double-precision floating-point number (default: 0.0)

Elevation at end position.

REFERENCE_LINE_OFFSET_Z

Double-precision floating-point number (default: 0.0)

Global offset for elevation.

REFERENCE_LINE_START_LON

Double-precision floating-point number

Longitude of the start position in WGS 84 coordinates.

REFERENCE_LINE_START_LAT

Double-precision floating-point number

Latitude of start position in WGS 84 coordinates.

REFERENCE_LINE_END_LON

Double-precision floating-point number

Longitude of end position in WGS 84 coordinates.

REFERENCE_LINE_END_LAT

Double-precision floating-point number

Latitude of end position in WGS 84 coordinates.

REFERENCE_LINE_START_ALT

Double-precision floating-point number

Altitude of start position in WGS 84 coordinates.

REFERENCE_LINE_END_ALT

Double-precision floating-point number

Altitude of end position in WGS 84 coordinates.

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.

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
$!********************************

4.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.

Keyword
$ROAD_CRG_MPRO
Contents
Parameter Values Description

GELL_A

Double-precision floating-point number (default: 0.0)

Semi-major axis of user-defined global ellipsoid.

GELL_B

Double-precision floating-point number (default: gell_a)

Semi-minor axis of user-defined global ellipsoid.

GELL_NM

  • WGS84,

  • USERDEFINED,

  • AIRY1830,

  • AIRYMODIFIED1849,

  • BESSEL1841,

  • BESSELMODIFIED,

  • BESSELNAMIBIAGLM,

  • BESSELDHDN,

  • CLARKE1866,

  • CLARKE1866AUTHALICSPHERE,

  • CLARKE1880IGN,

  • GRS1980,

  • GRS1980AUTHALICSPHERE,

  • INTERNATIONAL1924,

  • INTERNATIONAL1924AUTHALICSPHERE,

  • KRASSOWSKY1940

  • (default: WGS84)

Identifier of the global ellipsoid.

TRAN_NM

  • NOP,

  • HL7,

  • HN7,

  • HS7

  • (default: NOP)

Identifier of datum transformation type.

NOP

No transformation.

HL7

7-parameter linear Helmert transformation.

HN7

7-parameter nonlinear Helmert transformation.

HS7

7-parameter simple Helmert transformation.

TRAN_DS

Double-precision floating-point number (default: 0.0)

Helmert transformation parameter: scalar scaling factor minus one (tran_ds = m - 1).

TRAN_RX

Double-precision floating-point number (default: 0.0)

Helmert transformation parameter: rotation around the x-axis.

TRAN_RY

Double-precision floating-point number (default: 0.0)

Helmert transformation parameter: rotation around the y-axis.

TRAN_RZ

Double-precision floating-point number (default: 0.0)

Helmert transformation parameter: rotation around the z-axis.

TRAN_TX

Double-precision floating-point number (default: 0.0)

Helmert transformation parameter: translation along the x-axis.

TRAN_TY

Double-precision floating-point number (default: 0.0)

Helmert transformation parameter: translation along the y-axis.

TRAN_TZ

Double-precision floating-point number (default: 0.0)

Helmert transformation parameter: translation along the z-axis.

LELL_A

Double-precision floating-point number (default: 0.0)

Semi-major axis of the local ellipsoid.

LELL_B

Double-precision floating-point number (default: lell_a)

Semi-minor axis of the local ellipsoid.

LELL_NM

  • WGS84,

  • USERDEFINED,

  • AIRY1830,

  • AIRYMODIFIED1849,

  • BESSEL1841,

  • BESSELMODIFIED,

  • BESSELNAMIBIAGLM,

  • BESSELDHDN,

  • CLARKE1866,

  • CLARKE1866AUTHALICSPHERE,

  • CLARKE1880IGN,

  • GRS1980,

  • GRS1980AUTHALICSPHERE,

  • INTERNATIONAL1924,

  • INTERNATIONAL1924AUTHALICSPHERE,

  • KRASSOWSKY1940

  • (default: WGS84)

Identifier of the local ellipsoid.

PROJ_NM

GK3_0 …​ GK3_119, GK6_0 …​ GK6_59, UTM_01C …​ UTM_60X, TM_0 …​ TM_359, TM

Identifier of the map projection

GK3_0 …​ GK3_119

Gauss-Krüger with 3-degree zones with appended zone number.

GK6_0 …​ GK6_59

Gauss-Krüger with 6-degree zones with appended zone number.

UTM_01C …​ UTM_60X

Universal transverse Mercator with appended zone number and band letter.

TM_0 …​ TM_359

Transverse Mercator, with appended center meridian (degree east).

TM

Transverse Mercator using map projection parameters PROJ_* (user-defined or default).

PROJ_F0

Double-precision floating-point number (default: 1.0)

Map projection parameter: center meridian scaling.

PROJ_P0

Double-precision floating-point number (default: 0.0)

Map projection parameter: latitude of origin.

PROJ_L0

Double-precision floating-point number (default: 0.0)

Map projection parameter: longitude of origin.

PROJ_E0

Double-precision floating-point number (default: 0.0)

Map projection parameter: false easting.

PROJ_N0

Double-precision floating-point number (default: 0.0)

Map projection parameter: false northing.

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.

Examples
$ROAD_CRG_MPRO

PROJ_NM = 'UTM_32U'

4.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.

OpenCRG coord sys
Figure 4. A channel corresponds to a column 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.

Keyword
$KD_Definition
Contents
Definition Description

#:KRBI

Binary data format using numbers of type real

#:KDBI

Binary data format using numbers of type double

#:LRFI

Human-readable plain-text format using numbers of type real

#:LDFI

Human-readable plain-text format using numbers of type double

D:reference line phi,rad

Data entries represent heading angles of the reference line in rad.

D:reference line banking,m/m

Data entries represent banking as dimensionless fraction.

D:reference line slope,m/m

Data entries represent slope as dimensionless fraction.

D:long section at v = X,m

Data entries represent a longitudinal cut at position X in meters. X corresponds to a v-coordinate.

D:long section X,m

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.

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.

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
$!********************************

4.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.

Keyword
$ROAD_CRG_OPTS
Contents

The options section contains options provided as key-value pairs.

Option Values Description

BORDER_MODE_U

0, 1, 2, 3, 4 (default: 2)

Returned z-value, when a query exceeds the beginning or the end of the road.

0

Return NaN or an error.

1

Return 0.

2

Return the last valid z-value at the given v-coordinate.

3

Repeat road data before the beginning and after the end of the road.

4

Mirror road data at the beginning and the end of the road.

BORDER_MODE_V

0, 1, 2, 3, 4 (default: 2)

Returned z-value, when a query exceeds the left side or the right side of the road.

0

Return NaN or an error.

1

Return 0.

2

Return the last valid z-value at the given u-coordinate.

3

Repeat road data after the left side and the right side of the road.

4

Mirror road data at the left side and the right side of the road.

BORDER_OFFSET_U

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.

BORDER_OFFSET_V

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.

BORDER_SMOOTH_UBEG

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.

BORDER_SMOOTH_UEND

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.

REFLINE_CONTINUATION

0, 1 (default: 0)

Mode for computing x/y-positions if a given u-coordinate is positioned outside the defined reference line.

0

Extrapolate the reference line at both ends.

1

Treat reference line as closed track, if possible.

WARN_MSGS

-1, 0, [1;∞[ (default: -1)

Number of warning messages displayed.

-1

All.

0

None.

[1;∞[

Max. number.

WARN_CURV_LOCAL

0, 1 (default: 0)

Check whether local curvature limit is exceeded.

0

Do not check local curvature.

1

Check local curvature.

WARN_CURV_GLOBAL

0, 1 (default: 0)

Check whether global curvature limit is exceeded.

0

Do not check global curvature.

1

Check global curvature.

CHECK_EPS

[1e-6; 1e-2] (default: 1e-6)

Expected minimal accuracy, used for numerical consistency checks.

CHECK_INC

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_TOL

[CHECK_EPS*CHECK_INC; 0.5*CHECK_INC] (default: 0.1*CHECK_INC)

Expected absolute tolerance, used for numerical consistency checks.

CHECK_PRO

[0.1*CHECK_INC; 1] (default: 5e-3)

Expected projection tolerance, used for numerical consistency checks.

CHECK_WGS

[0.1*CHECK_INC; 1000] (default: 10)

Expected WGS 84 tolerance, used for numerical consistency checks.

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.

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
$!*********************

4.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.

Keyword
$ROAD_CRG_MODS
Contents

The modifiers section contains modifiers provided as key-value pairs.

Modifier Values Description

REFPOINT_U

Double-precision floating-point number

u-coordinate of reference point for relocating by reference point.

REFPOINT_V

Double-precision floating-point number

v-coordinate of reference point for relocating by reference point.

REFPOINT_U_FRACTION

Double-precision floating-point number: [0.0, 1.0] (default: 0.0)

Relative u-coordinate of reference point for relocating by reference point.

REFPOINT_U_OFFSET

Double-precision floating-point number (default: 0.0)

Offset for u-coordinate of reference point for relocating by reference point.

REFPOINT_V_FRACTION

Double-precision floating-point number: [0.0, 1.0] (default: 0.0)

Relative v-coordinate of reference point for relocating by reference point.

REFPOINT_V_OFFSET

Double-precision floating-point number (default: 0.0)

Offset for v-coordinate of reference point for relocating by reference point.

REFPOINT_X

Double-precision floating-point number (default: 0.0)

x-coordinate of target position for relocating by reference point.

REFPOINT_Y

Double-precision floating-point number (default: 0.0)

y-coordinate of target position for relocating by reference point.

REFPOINT_Z

Double-precision floating-point number (default: 0.0)

z-coordinate of target position for relocating by reference point.

REFPOINT_PHI

Double-precision floating-point number (default: 0.0)

Absolute heading angle of target position for relocating by reference point.

REFLINE_ROTCENTER_X

Double-precision floating-point number (default: x-coordinate of starting position)

x-coordinate of rotation center for relocating by rotation and translation.

REFLINE_ROTCENTER_Y

Double-precision floating-point number (default: y-coordinate of starting position)

y-coordinate of rotation center for relocating by rotation and translation.

REFLINE_OFFSET_PHI

Double-precision floating-point number (default: 0.0)

Rotation angle for re-locating by rotation and translation.

REFLINE_OFFSET_X

Double-precision floating-point number (default: 0.0)

Offset in x-direction for relocating by rotation and translation.

REFLINE_OFFSET_Y

Double-precision floating-point number (default: 0.0)

Offset in y-direction for relocating by rotation and translation.

REFLINE_OFFSET_Z

Double-precision floating-point number (default: 0.0)

Offset in z-direction for relocating by rotation and translation.

SCALE_Z_GRID

Double-precision floating-point number (default: 0.0)

Factor for scaling the data in z-direction.

SCALE_SLOPE

Double-precision floating-point number (default: 0.0)

Factor for scaling slope in elevation data.

SCALE_BANKING

Double-precision floating-point number (default: 0.0)

Factor for scaling banking in elevation data.

SCALE_LENGTH

Double-precision floating-point number: ]0.0,∞] (default: 0.0)

Factor for scaling the data in u-direction.

SCALE_WIDTH

Double-precision floating-point number: ]0.0,∞] (default: 0.0)

Factor for scaling the data in v-direction.

SCALE_CURVATURE

Double-precision floating-point number: : [0.0,∞] (default: 0.0)

Factor for scaling the curvature.

GRID_NAN_MODE

0, 1, 2

Mode for replacing NaN values in road data borders.

0

Keep NaN values.

1

Replace NaN values with 0.

2

Replace NaN values with last valid value.

GRID_NAN_OFFSET

Double-precision floating-point number (default: 0.0)

Offset applied to replaced NaN values.

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.

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.

Rotating and shifting the reference line
$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).

Replacing NaN values at the border
$ROAD_CRG_MODS
GRID_NAN_MODE       = 1     ! replace NaN with z = 0
GRID_NAN_OFFSET     = 10    ! offset former NaN values by 10 m
$!************************

4.4.7. File reference

The optional file reference section contains references to other OpenCRG files.

The file reference section of an OpenCRG file may reference multiple files. This can be used to separate options and modifiers in control files from files containing actual road data. By referencing both a control file and a road data file, multiple combinations of options, modifiers, and road data can be created without copying the contents.

If resolving references results in conflicting definitions, the last definition takes precedence.

Keyword
$ROAD_CRG_FILE
Contents

File references use the following symbols for describing paths.

Symbol Function

/

Path delimiter.

.

Current directory.

..

Superordinate directory.

$

Reference to environment variable.

Rules
  • An OpenCRG file may contain a file reference section.

  • A file reference section may contain multiple file references.

  • 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.

Examples
File reference using an absolute path.
/home/name/crg-files/handmade_straight.crg
File reference using an absolute path split into 2 lines.
/home/name/crg-files/hand
made_straight.crg
File reference using a relative path.
./handmade_straight.crg
File reference using an environment variable ($crgpath).
$crgpath/handmade_straight.crg
File reference section containing two file references.
$ROAD_CRG_FILE
/home/name/crg-files/control_file.crg
/home/name/crg-files/road_data.crg
$!********

4.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.

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.

Keyword

None.

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.

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. The following three columns contain actual road surface data. One value on the right border of the road is missing.

Plain-text road data with 4 columns and 10 rows
$ROAD_CRG                          ! road parameters section
REFERENCE_LINE_INCREMENT =  0.50   ! 10 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
$!********************************
$KD_DEFINiTION                     ! data definition section
#:LRBI                             ! plain-text data, numbers of type real
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
$!********************************
$
0.0000000 0.0000000 0.0000000 0.0000000
0.0000000 0.0000000 0.0000000 0.0000000
0.0000000 0.0000000 0.0000000 0.0000000
0.0000000 0.0111111 0.0111111 0.0000000
0.0000000 0.0000000 0.0000000 0.0000000
0.0111111 *missing* 0.0000000 0.0111111
0.0111111 0.0111111 0.0111111 0.0222222
0.0111111 0.0111111 0.0222222 0.0333333
0.0111111 0.0111111 0.0111111 0.0222222
0.0111111 0.0000000 0.0000000 0.0111111

4.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.

5. Setting up the OpenCRG tools

5.1. Downloading the software package

The latest stable version of OpenCRG is available on the ASAM website. The software package contains:

  • Sample OpenCRG files.

  • Source code of the C-API, including test programs and samples.

  • MATLAB tools, including test scripts and samples.

  • OpenCRG documentation.

Steps
  1. Open https://www.asam.net/standards/detail/opencrg/.

  2. Navigate to the Download area.

  3. Follow the instructions to download the software package.

  4. Download the ZIP archive.

  5. Unpack the archive into a local directory.

What to do next
  • Compile the C source code.

  • Initialize the MATLAB tools.

5.2. Setting up the C-API

5.2.1. Contents of the C-API

The C-API is located in open-crg/c-api/ and comprises the following:

baselib/

Base library for working with OpenCRG files in C.

demo/

Sample programs demonstrating the use of the C-API.

test/

Programs for testing the C-API.

5.2.2. Header files of the C-API

The header files of the C-API are stored in open-crg/c-api/baselib/inc/ and comprise the following:

crgBaseLib.h

Provides the interface to the OpenCRG methods. Include this header file when writing your own applications.

crgBaseLibPrivate.h

Used internally by the library’s components. Includes crgBaseLib.h.

5.2.3. Source files of the C-API

The source files of the C-API are stored in open-crg/c-api/baselib/src/ and comprise the following:

crgContactPoint.c

Contact point management.

crgEvalpk.c

Routines for evaluating heading and curvature.

crgEvaluv2xy.c

Routines for evaluating x/y-coordinates from u/v-coordinates.

crgEvalxy2uv.c

Routines for evaluating u/v-coordinates from x/y-coordinates.

crgEvalz.c

Routines for evaluating z-values.

crgLoader.c

Routines for decoding files and loading data.

crgMgr.c

Overall data management.

crgMsg.c

Message and log handling.

crgOptionMgmt.c

Management of options and modifiers.

crgPortability.c

Routines which might be subject to portability issues.

crgStatistics.c

Routines for calculating data set statistics.

5.2.4. Compiling the C-API using Makefiles

Using the provided Makefiles is the most convenient way of compiling the C-API.

Prerequisites
  • You downloaded and unpacked the OpenCRG software package.

  • You have installed the C-compiler gcc on your computer.

  • You have set up a standard make environment on your computer.

  • The following directories exist: open-crg/c-api/test/bin/, open-crg/c-api/demo/bin/.

Steps
  1. Open a command line interpreter.

  2. Change to the c-api directory.

  3. Run make.

Result
  • A library containing all object files of the basic library is generated in c-api/baselib/lib/.

  • Executable test files are generated in open-crg/c-api/test/bin/.

  • Executable demo files are generated in open-crg/c-api/demo/bin/.

What to do next

Test the C-API to ensure that it is set up correctly.

5.2.5. Compiling the C-API using a shell script

Using a shell script for compiling is appropriate, if you cannot compile the software package using the provided make files.

In contrast to using the Makefiles, no library containing the object files of the basic library is generated.

Prerequisites
  • You downloaded and unpacked the OpenCRG software package.

  • Your computer provides an environment for executing shell scripts.

  • You have installed a C-compiler on your computer.

Steps
  1. Open the shell script c-api/compileScript.sh in a text editor.

  2. Find the variable COMP and set it to the name of your compiler.

  3. Save your changes to the script.

  4. Execute the script.

Result
  • Executable test files are generated in c-api/test/bin/.

  • Executable demo files are generated in c-api/demo/bin/.

What to do next

Test the C-API to ensure that it is set up correctly.

5.2.6. Compiling the C-API using the command line

The C-API can be compiled manually, for example, to compile only selected sample programs.

Prerequisites
  • You downloaded and unpacked the OpenCRG software package.

  • A C-compiler is installed on your computer.

Steps

The procedure depends on the C-compiler. When compiling, observe the following hints:

  • Set your include file search path to baselib/inc.

  • Always compile in combination with all .c-files in baselib/src.

What to do next

Test the C-API to ensure that it is set up correctly.

5.2.7. Testing the C-API

The software package provides programs for testing various aspects of the C-API. Successfully running these test programs ensures that the C-API is set up correctly. These tests are also used for acceptance tests of the C-API.

Prerequisites
  • You have compiled the C-API.

  • Your computer provides an environment for executing shell scripts.

  • You have installed gnuplot on your computer for creating images.

Steps
  1. To run all tests for evaluation options, execute the script c-api/test/bin/testOptions.sh.

  2. To run all tests for data set modifiers, execute the script c-api/test/bin/testModifiers.sh.

Results
  • The C-API is set up successfully.

  • Images illustrating the various options and modifiers are created.

5.2.8. Source code of test programs

The source code of the test programs for the C-API is stored in open-crg/c-api/test/ and comprises the following:

Dump/

Read an OpenCRG file and write all values (x, y, z, u, v) into a text file crgDump.txt.

MemTest/

Test allocating and releasing OpenCRG data sets.

MultiCp/

Test multiple contact points.

MultiRead/

Read multiple data files and evaluate the last file.

PerfTest/

Tool for evaluating the performance of the library.

Scan/

Perform an x/y-scan of an OpenCRG data set.

Verify/

Reads an OpenCRG file and a reference text file containing x/y/z data or x/y/z/u/v data. Calculates the z-values at the given x/y locations from the OpenCRG file and compares the result with the z-values from the reference text file.

5.2.9. Running the sample programs

The software package contains several sample programs illustrating the use of the C-API:

crgSimple

Perform a series of z-data queries using x/y-coordinates.

crgReader

Read an OpenCRG file and print debug information.

crgEvalxyuv

Perform a series of conversions between x/y-coordinates and u/v- coordinates and check the results for consistency.

crgEvalZ

Perform a series of advanced z-data queries from given x/y- coordinates and u/v-coordinates.

crgEvalOpts

Collection of tests involving data set modifiers and evaluation options.

Prerequisites

You have compiled the C-API.

Steps
  1. Open a command line interpreter.

  2. Switch to the directory containing the executable of the sample program. The executables are stored in open-crg/c-api/demo/bin/.

  3. Run [program] -help to display information about the available options.

  4. Run [program] [options] <OpenCRG file> to run the program with the set options for the selected OpenCRG file.

5.2.10. Source code of sample programs

The source code of the sample programs for the C-API is stored in open-crg/c-api/demo/ and comprises the following:

EvalOptions/src/

Source code for crgEvalOpts.

EvalXYnUV/src/

Source code for crgEvalxyuv.

EvalZ/src/

Source code for crgEvalZ.

Reader/src/

Source code for crgReader.

Simple/src/

Source code for crgSimple.

5.3. Setting up the MATLAB tools

5.3.1. Contents of the MATLAB tools

The MATLAB tools are stored in open-crg/matlab/ and comprise the following:

demo/

Scripts demonstrating the use of the base library.

lib/

Base library for working with OpenCRG files in MATLAB.

test/

Scripts for testing the MATLAB tools.

crg_init.m

Script for initializing the MATLAB tools.

crg_intro.m

Script for displaying an introduction to the MATLAB implementation of OpenCRG.

5.3.2. Library files of the MATLAB tools

The library files of the MATLAB tools are stored in open-crg/matlab/lib/ and comprise the following:

Table 4. Evaluation tools
Filename Description

crg_eval_enh2xyz.m

Transform points in e/n/h to x/y/z.

crg_eval_llh2xyz.m

Transform points in llh to x/y/z.

crg_eval_u2crv.m

Evaluate curvature at reference line positions.

crg_eval_u2phi.m

Evaluate heading angles at reference line positions.

crg_eval_uv2iuiv.m

Evaluate index positions of grid positions.

crg_eval_uv2xy.m

Evaluate local coordinates of grid positions.

crg_eval_uv2z.m

Evaluate z at grid position.

crg_eval_xy2uv.m

Transform points in x/y to u/v.

crg_eval_xy2z.m

Evaluate z at x/y-position.

crg_eval_xyz2enh.m

Transform point in x/y/z to e/n/h.

crg_eval_xyz2llh.m

Transform point in x/y/z to l/l/h.

Table 5. Visualization and analysis tools
Filename Description

copy_ax2fig.m

Copy current axes object to new figure.

crg_figure.m

Set up OpenCRG figure.

crg_isequal.m

Compare two OpenCRG data sets.

crg_peakfinder.m

Detect peaks in a OpenCRG data.

crg_plot_elgrid_cross_sect.m

Plot z-values over latitudinal cuts.

crg_plot_elgrid_limits.m

Plot the outer grid limits.

crg_plot_elgrid_long_sect.m

Plot z-values over longitudinal cuts.

crg_plot_elgrid_uvz_map.m

Plot z-values as uncurved orthographic image.

crg_plot_elgrid_xyz_map.m

Plot z-values as curved three-dimensional image.

crg_plot_refline_curvature.m

Plot curvature along the reference line.

crg_plot_refline_elevation.m

Plot the z-values along the reference line.

crg_plot_refline_heading.m

Plot heading angle along the reference line.

crg_plot_refline_slope_bank.m

Plot slope and banking along the reference line.

crg_plot_refline_xyz_map.m

Plot reference line in x/y/z-coordinates.

crg_plot_refline_xy_map_and_curv.m

Plot reference line including curvature.

crg_plot_refline_xy_overview_map.m

Plot reference line in x/y-coordinates.

crg_plot_refpnt_distances.m

Plot distance of reference points to reference line.

crg_plot_road_uv2uvz_map.m

Plot road surface over a given uncurved grid.

crg_plot_road_uv2xyz_map.m

Plot road surface over a given curved grid.

crg_plot_road_uvz_map.m

Plot road surface as uncurved orthographic image.

crg_plot_road_xyz_map.m

Plot road surface as curved three-dimensional image.

crg_show.m

Visualize CRG data.

crg_show_elgrid_cuts_and_limits.m

Visualize the cuts and limits of the CRG

crg_show_elgrid_surface.m

Visualize z-values.

crg_show_info.m

Display information about the CRG.

crg_show_isequal.m

Visualize the result of comparing two OpenCRG files.

crg_show_peaks.m

Visualize peaks.

crg_show_refline_elevation.m

Visualize elevation along the reference line.

crg_show_refline_map.m

Visualize the reference line.

crg_show_refpnts_and_refline.m

Visualize reference points and reference line.

crg_show_road_surface.m

Visualize the road surface.

crg_show_road_uv2surface.m

Visualize the road surface on a given grid.

crg_surf.m

Plot a three-dimensional surface.

Table 6. File input and output tools
Filename Description

crg_read.m

Read OpenCRG file.

crg_single.m

Convert OpenCRG road data to type single.

crg_wrap.m

Wrap heading angles to +/- pi range.

crg_write.m

Write OpenCRG file.

ipl_demo.m

IPLOS write/read demonstration.

ipl_read.m

Read IPLOS file.

ipl_write.m

Write IPLOS file.

sdf_add.m

Add block to struct data file.

sdf_cut.m

Cut block from struct data file.

str_num2strn.m

Convert number to string of given length.

Table 7. Checking tools
Filename Description

crg_check.m

Run all OpenCRG data checks.

crg_check_curvature.m

Check OpenCRG curvature data.

crg_check_data.m

Check, fix, and complement OpenCRG data.

crg_check_head.m

Check OpenCRG road parameters data.

crg_check_mods.m

Check modifier data.

crg_check_mpro.m

Check OpenCRG map projection data.

crg_check_opts.m

Check OpenCRG options data.

crg_check_single.m

Check core OpenCRG data for type single.

crg_check_wgs84.m

Check OpenCRG WGS 84 data.

Table 8. modification tools
Filename Description

crg_append.m

Append a second compatible OpenCRG to a first OpenCRG.

crg_b2z.m

Apply banking to OpenCRG data.

crg_cut_iuiv.m

Cut out a part of a OpenCRG road.

crg_ext_banking.m

Extract banking from OpenCRG data.

crg_ext_slope.m

Extract slope from OpenCRG data.

crg_filter.m

Apply filter to OpenCRG data.

crg_flip.m

Flip OpenCRG data.

crg_limiter.m

Limits z-values in OpenCRG data.

crg_map_uv2uv.m

Map z-values from one grid to another.

crg_map_xy2xy.m

Map z-values from one local coordinate system to another.

crg_mods.m

Apply modifiers to data.

crg_rerender.m

Re-render OpenCRG data for a new u/v-grid.

crg_s2z.m

Apply slope to OpenCRG data.

crg_separate_sb.m

Separate slope and banking.

smooth_firfilt.m

Smooth input signals with symmetric FIR filter.

Table 9. Generation tools
Filename Description

crg_check_uv_descript.m

Check uv_descript and create a v-profile.

crg_gen_csb2crg0.m

Generate synthetic OpenCRG data.

crg_gen_ppxy2phi.m

Generate reference line heading from polynomial.

crg_gen_pxy2ppxy.m

Generates smooth polynomial from reference points.

crg_perform2surface.m

Generate synthetical surface.

Table 10. Geographic referencing tools
Filename Description

crg_wgs84_crg2html.m

Generate HTML file to visualize OpenCRG data in a map.

crg_wgs84_dist.m

Evaluate distance and bearing between WGS 84 positions.

crg_wgs84_invdist.m

Calculate WGS 84 positions by distance and bearing.

crg_wgs84_setend.m

Set WGS 84 end coordinate.

crg_wgs84_wgs2url.m

Generate URL to show WGS 84 information on Google Maps

crg_wgs84_wgsxy2wgs.m

Transform points in x/y-coordinates to WGS 84 coordinates using two references.

crg_wgs84_xy2wgs.m

Transform points in x/y-coordinates to WGS 84 coordinates.

map_check.m

Check and update DAT struct.

map_check_elli.m

Check and update ellipsoid struct.

map_check_proj.m

Check and update map projection struct.

map_check_tran.m

Check and update datum transformation struct.

map_ecef2ecef.m

Datum transformation in ECEF system.

map_ecef2geod.m

Convert points from ECEF system to geodetic system.

map_geod2ecef.m

Convert points from geodetic system to ECEF system.

map_geod2pmap.m

Forward map projection.

map_geod2pmap_tm.m

Forward transverse Mercator projection.

map_global2plocal.m

Forward projection: global to projected local.

map_intro.m

MAP routines introduction

map_plocal2global.m

Backward projection: projected local to global.

map_pmap2geod_tm.m

Backward projection: transverse Mercator.

map_ptm_north2initiallat.m

Transverse Mercator utility function.

map_ptm_phi2marc.m

Transverse Mercator utility function: meridional arc.

map_wgs2html.m

Generate HTML file to visualize WGS 84 data in a map.

5.3.3. Initializing the MATLAB tools

Initializing the MATLAB tools adds them to the MATLAB search path. This allows MATLAB to find functions by their name.

Additionally, a new directory for holding temporary data is needed. Such a directory is required when running the demo scripts or tests.

Prerequisites

You have downloaded and unpacked the OpenCRG software package.

Steps
  1. In MATLAB, switch to the Command Window.

  2. Run run path-to-opencrg/matlab/crg_init to add the MATLAB tools to the MATLAB search path.

  3. Run mkdir path-to-opencrg/matlab/temp to create a directory for temporary data.

  4. Run cd path-to-opencrg/matlab/temp to change the current directory to the location of the directory for temporary data.

Result

The MATLAB tools are added to the search path. MATLAB’s current directory points to the newly created directory for temporary data.

What to do next

Test the MATLAB tools to ensure that they are set up correctly.

5.3.4. Getting help

The OpenCRG MATLAB files contain comments formatted for help display. The help comments contain the following information:

  • Short description of the function

  • Input parameters and return values

  • Usage examples

  • Related functions

Prerequisites

You have initialized the MATLAB tools.

Steps
  1. In MATLAB, switch to the Command Window.

  2. To get an overview of the MATLAB implementation, run crg_intro.

  3. To get help for a specific function, run help function.

Result

The help text is displayed in the Command Window.

5.3.5. Testing the MATLAB tools

Testing the MATLAB tools makes sure that they are set up correctly. The OpenCRG software package provides several scripts that you can use for testing. These scripts are stored in /matlab/demo/ and /matlab/test/

Before running the actual tests, the required OpenCRG data structures must be created and written to file. You can use the command crg_demo to create the required files.

All test files and demo files may further be used as examples on how to use the MATLAB tools.

Prerequisites
  • You have initialized the MATLAB tools.

  • MATLAB’s current directory is set to the directory for temporary files.

Steps
  1. Run crg_demo to create the required OpenCRG data structures and write them to file.

  2. Run crg_demo_demoname, to run the demo of the respective name.

  3. Run crg_test_testname, to run the test of the respective name.

5.3.6. Test scripts

The test scripts for the MATLAB tools are stored in open-crg/matlab/test/ and comprise the following:

crg_test_append.m

Test concatenating two OpenCRG files.

crg_test_continuesTrack.m

Test the reference line continuation option.

crg_test_curvature.m

Test global and local curvature as well as reading and writing flags.

crg_test_eval_uv2iuiv.m

Test the transformation of u/v-coordinates to index positions.

crg_test_ext_sb.m

Extract slope and banking from an OpenCRG file.

crg_test_filter.m

Test the application of various filters on OpenCRG data.

crg_test_gen_csb2crg0.m

Generate synthetic road with curvature, banking, and slope

crg_test_gen_road.m

Generate synthetic road and write it to an OpenCRG file.

crg_test_isequal.m

Test whether the results of various invariant modifications to an OpenCRG file are equal to the unmodified file.

crg_test_limiter.m

Test limiting z-values to a specific range.

crg_test_map_pro.m

Test functions related to map projection.

crg_test_map_uv2uvAxy2xy.m

Test mapping z-values from one OpenCRG file to another.

crg_test_options.m

Display results of various options settings.

crg_test_peakfinder.m

Test whether the MATLAB tools find artificially created peaks.

crg_test_rerender.m

Test whether OpenCRG files can be re-rendered with different u/v-spacings.

5.3.7. Demo scripts

The demo scripts for the MATLAB tools are located in open-crg/matlab/demo/ and comprise the following:

crg_demo.m

Create a set of demo files.

crg_demo_belgian_block.m

Load and visualize ../crg-bin/belgian_block.crg.

crg_demo_convert2bin.m

Convert ../crg-txt/handmade_curved.crg to binary representation.

crg_demo_convert2txt.m

Convert ../crg-bin/belgian_block.crg to text representation.

crg_demo_country_road.m

Load and visualize ../crg-bin/country_road.crg.

crg_demo_gen_refline.m

Generate an OpenCRG file with a smooth reference line.

crg_demo_gen_sl_mue.m

Generate a synthetic OpenCRG file with friction coefficients.

crg_demo_gen_sl_road.m

Generate a synthetic OpenCRG file representing a complete road.

crg_demo_gen_sl_surf.m

Generate a synthetic OpenCRG file representing a straight road.

crg_demo_gen_surface.m

Generate a OpenCRG file for a given reference line from measurement data.

crg_demo_gen_syntheticStraight.m

Generate a synthetic OpenCRG file representing a straight road.

crg_demo_gen_target.m

Generate a surface OpenCRG file.

crg_demo_map_transformation.m

Perform geodetic transformations (e.g UTM → WGS 84).

crg_demo_scale_data.m

Scale OpenCRG data.

6. Using the OpenCRG tools

6.1. Usage of the C-API

The C-API comprises methods for the following tasks:

  • Reading OpenCRG files.

  • Setting modifiers and options.

  • Evaluating OpenCRG data.

The C-API is especially suitable for applications for which fast evaluation is important. Typical use cases include driving simulators or test rigs.

A data set is the instance of data read from an OpenCRG file into memory. A data set is identified by a unique integer ID. This ID is returned by the data loader method. A data set stores the actual road data as well as modifiers and options defined in the file.

After the file has been read, the modifiers of the data set may be replaced, deleted or extended via API calls referring to that data set. Once the modifiers are defined, they must be applied via an API call.

A contact point provides access to a data set. In simulations, contact points can be used to model the touching point between a tire and the road surface. A contact point inherits all options from the corresponding data set. The options of a contact point may be replaced, deleted or extended via API calls referring to that contact point. In contrast to modifiers, options are applied implicitly whenever an evaluation is performed.

6.2. Usage of the MATLAB tools

The MATLAB tools contain scripts for the following tasks:

  • Reading OpenCRG files.

  • Setting modifiers and options.

  • Evaluating OpenCRG data.

  • Manipulating OpenCRG data.

  • Generating OpenCRG data.

  • Visualizing and analyzing OpenCRG data.

  • Mapping OpenCRG data to geographical positions.

  • Writing OpenCRG file.

The MATLAB tools are especially suitable for applications that require extended functionalities for processing, analysis and visualization. Typical use cases include generating OpenCRG files either synthetically or from measurement data and numerical simulations of driving dynamics.

When an OpenCRG file is loaded, all data associated with that file is stored in a single structure array. This structure array has the following fields:

head

Structure array containing data corresponding to the road parameters section and the data definition section.

mods

Structure array containing modifiers read from file or set via function calls.

opts

Structure array containing options read from file or set via function calls.

ct

Cell array containing header information text. Mandatory when writing to file, otherwise optional.

struct

Optional cell array of further structured data, used for file output.

filenm

File name of the associated OpenCRG file.

z

Array of z-values.

u

Definition of u-values.

v

Definition of v-values.

b

Vector of banking values (optional).

p

Vector of heading angles (optional).

s

Vector of slope values (optional).

mpro

Map projection data.

fopt

Figure options.

A minimal OpenCRG data set must at least define u, v and z.

For more detailed information on individual fields and subfields, run crg_intro from the MATLAB Command Window.

6.3. Reading OpenCRG files

Reading an OpenCRG files loads its content into memory.

int crgLoaderReadFile( const char* file )

Read the OpenCRG file file and returns an integer data set ID.

int crgDataSetRelease( int dataSetId )

Destroy the OpenCRG data set dataSetId.

[data] = crg_read(file)

Read the OpenCRG file file and returns a structure array data containing the OpenCRG data.

6.3.3. Examples

C examples
/* load CRG file */
int dataSetId = crgLoaderReadFile( 'demo.crg' );
MATLAB examples
% load CRG file
data = crg_read('demo.crg');

6.4. Setting and applying modifiers

Modifiers provide a way to alter OpenCRG data without changing the actual data in the file.

With the C-API, you use function calls to set modifiers. For all modifiers and values, symbolic constants are defined in opencrg/c-api/baselib/inc/crgBaseLib.h. These constants should be used instead of their integer equivalents to improve readability of the code.

With MATLAB, you set modifiers by directly accessing the mods field of a data set using dot notation.

Modifiers, whether defined in an OpenCRG file or via function calls, are not applied automatically. They must be applied explicitly with a separate function call.

6.4.1. Prerequisites

You have loaded an OpenCRG data set.

6.4.2. Corresponding C functions

int crgDataSetModifierSetInt( int dataSetId, unsigned int modId, int modValue )

Set the integer modifier modId of the data set dataSetId to the value modValue.

int crgDataSetModifierSetDouble( int dataSetId, unsigned int modId, double modValue )

Set the double modifier modId of the data set dataSetId to the value modValue.

int crgDataSetModifierGetInt( int dataSetId, unsigned int modId, int* modValue )

Get the current value of the integer modifier modID of the data set dataSetId and store it in modValue.

extern void crgDataSetModifiersPrint( int dataSetId )

Print the current modifier settings of the data set dataSetId.

int crgDataSetModifierGetDouble( int dataSetId, unsigned int modId, double* modValue )

Get the current value of the double modifier modID of the data set dataSetId and store it in modValue.

int crgDataSetModifierRemove( int dataSetId, unsigned int modId )

Remove the modifier modID from the data set dataSetId.

int crgDataSetModifierRemoveAll( int dataSetId )

Remove all modifiers from the data set dataSetId.

void crgDataSetModifierSetDefault( int dataSetId )

Set all modifiers of the data set dataSetId to their default values.

void crgDataSetModifiersApply( int dataSetId )

Apply set modifiers to the data set dataSetId. If no modifiers are defined, the default modifier values are applied.

6.4.3. Corresponding MATLAB functions

[data] = crg_mods(data)

Apply modifiers in data.mods to the OpenCRG data in data. Afterwards, remove all modifiers from data.mods. If data.mods does not exist, default modifier values are applied. If data.mods is empty, no modifiers are applied.

6.4.4. Examples

C examples

The following example shows how to set and apply modifiers using the C-API.

 /* load CRG file */
int dataSetId = crgLoaderReadFile( 'demo.crg' );

/* remove modifiers defined in file */
crgDataSetModifierRemoveAll( dataSetId );

/* set NaN-handling modifier using symbolic constants */
crgDataSetModifierSetInt( dataSetId, dCrgModGridNaNMode, dCrgGridNaNKeepLast );

/* set offset-position modifiers using both symbolic constants and numerical values */
crgDataSetModifierSetDouble( dataSetId, dCrgModRefLineOffsetX,  100.0 );
crgDataSetModifierSetDouble( dataSetId, dCrgModRefLineOffsetY,  200.0 );
crgDataSetModifierSetDouble( dataSetId, dCrgModRefLineOffsetZ,   10.0 );

/* apply modifiers to data set */
crgDataSetModifiersApply( dataSetId );
MATLAB examples

The following example shows how to set and apply modifiers using the MATLAB tools.

% load CRG file
data = crg_read('demo.crg');

% create mods struct
data.mods = struct;

/* set NaN-handling modifier */
data.mods.gnan = 2;

/* set offset-position modifiers */
data.mods.rlox = 100;
data.mods.rloy = 200;
data.mods.rloz = 10;

/* apply modifiers to data set */
data = crg_mods(data);

6.5. Creating and deleting contact points

In order to evaluate data with the C-API, you must create one or more contact points. Contact points provide access to a given data set. A contact point is identified by a unique integer ID. This ID is returned by the contact-point creation method. The number of contact points per data set is not limited.

In simulations, contact points can be used to model the touching point between a tire and the road surface.

When creating multithreaded applications to parallelize evaluation calls, create a separate contact point for each thread. Sharing contact points across different threads destroys data associated with that contact point.

6.5.1. Prerequisites

  • You have loaded an OpenCRG data set.

  • You have set and applied modifiers.

6.5.2. Corresponding C functions

int cpId = crgContactPointCreate( int dataSetId )

Create a contact point with the ID cpId for the data set dataSetId.

int crgContactPointDelete( int cpId )

Delete the contact point with the ID cpId.

int crgContactPointDeleteAll( int dataSetId )

Delete all contact points associated with the data set dataSetId.

6.5.3. Corresponding MATLAB functions

The MATLAB tools do not use contact points.

6.5.4. Examples

C examples

The following example shows how to create two contact points with the C-API.

double z;

/* load CRG file */
int dataSetId = crgLoaderReadFile( 'demo.crg' );

/* create two contact points */
int cpId1 = crgContactPointCreate( dataSetId );
int cpId2 = crgContactPointCreate( dataSetId );

6.6. Setting options

With the C-API, you set options via function calls. For all options and values, symbolic constants are defined in opencrg/c-api/baselib/inc/crgBaseLib.h. You should use the symbolic constants rather than their integer equivalents to make your code easier to read.

When you use the MATLAB tools to evaluate data, options stored with OpenCRG data are automatically taken into account. With MATLAB, you set options by directly accessing the opts field of a data set using dot notation.

Options, whether defined in an OpenCRG file or via function calls, are applied automatically when executing an evaluation call.

6.6.1. Prerequisites

  • You have loaded an OpenCRG data set.

  • You have set and applied modifiers.

  • You have created a contact point (C only).

6.6.2. Corresponding C functions

int crgContactPointOptionSetInt( int cpId, unsigned int optionId, int optionValue )

Set the integer option optionId of the contact point cpId to the value optionValue.

int crgContactPointOptionSetDouble( int cpId, unsigned int optionId, double optionValue )

Set the double option optionId of the contact point cpId to the value optionValue.

int crgContactPointOptionGetInt( int cpId, unsigned int optionId, int* optionValue )

Get the current value of the integer option optionId of the contact point cpId and store it in option value.

int crgContactPointOptionGetDouble( int cpId, unsigned int optionId, double* optionValue )

Get the current value of the double option optionId of the contact point cpId and store it in option value.

void crgContactPointOptionsPrint( int cpId )

Print the current option settings of the contact point cpId.

int crgContactPointOptionRemove( int cpId, unsigned int optionId )

Remove the option optionID from the contact point cpId.

int crgContactPointOptionRemoveAll( int cpId )

Remove all options from the contact point cpId.

void crgContactPointSetDefaultOptions( int cpId )

Set all options of the contact point cpId to their default values.

6.6.3. Corresponding MATLAB functions

Options are set by directly accessing the opts field of a data set using dot notation.

6.6.4. Examples

C examples

The following example shows how to set options using the C-API.

/* load CRG file */
int dataSetId = crgLoaderReadFile( 'demo.crg' );

/* create contact point */
int cpId = crgContactPointCreate( dataSetId );

/* set border mode options to "Return NaN" */
crgContactPointOptionSetInt( cpId, dCrgCpOptionBorderModeU, dCrgBorderModeNone );
crgContactPointOptionSetInt( cpId, dCrgCpOptionBorderModeV, dCrgBorderModeNone );

/* evaluate z at (u,v) = [100 0] */
crgEvaluv2z( cpId, 100, 0, &z );
MATLAB examples

The following example shows how to set options using the MATLAB tools.

% load CRG file
data = crg_read('demo.crg');

% set border mode options to "Return NaN"
data.opts.bdmu = 0;
data.opts.bdmv = 0;

% plot road surface in u/v-coordinates
crg_show_road_uv2surface(data, u, v);

6.7. Evaluating OpenCRG data

Evaluation routines provide access to road data. Additionally, you can use the evaluation routines to transform data between different coordinate systems.

6.7.1. Prerequisites

  • You have loaded an OpenCRG data set.

  • You have set and applied modifiers.

  • You have created a contact point (C only).

  • You have set options.

6.7.2. Corresponding C functions

void crgEvaluv2z( int cpId, double u, double v, double* z )

Evaluate the z-value at a given u/v-position for contact point cpId.

void crgEvalxy2z( int cpId, double u, double v, double* z )

Evaluate the z-value at a given x/y-position for contact point cpId.

void crgEvaluv2xy( int cpId, double u, double v, double* x, double* y )

Evaluate the x/y-position of a given u/v-position for contact point cpId.

void crgEvalxy2uv( int cpId, double x, double y, double* u, double* v )

Evaluate the u/v-position of a given x/y-position for contact point cpId.

void crgEvaluv2pk( int cpId, double u, double v, double* phi, double* crv )

Evaluate the heading angle phi and the curvature crv at a given u/v-position for contact point cpId.

int crgEvalxy2pk( int cpId, double x, double y, double* phi, double* curv )

Evaluate the heading angle phi and the curvature crv at a given x/y-position for contact point cpId.

6.7.3. Corresponding MATLAB functions

[pz, data] = crg_eval_uv2z(data, puv)

Evaluate the z-values at the given u/v-positions for data set data.

[pz, data] = crg_eval_xy2z(data, pxy)

Evaluate the z-values at the given x/y-positions for data set data.

[pxy, data] = crg_eval_uv2xy(data, puv)

Evaluate the x/y-positions of the given u/v-positions for data set data.

[puv, data] = crg_eval_xy2uv(data, pxy)

Evaluate the u/v-positions of the given x/y-positions for data set data.

[iu, iv] = crg_eval_uv2iuiv(data, u, v)

Evaluate the index positions iu, iv of the given u/v-positions for data set data.

[phi, data] = crg_eval_u2phi(data, pu)

Evaluate the heading angles phi at given u-positions for data set data.

[crv, data] = crg_eval_u2crv(data, pu)

Evaluate the curvature values crv at given u-positions for data set data.

[pxyz, data] = crg_eval_enh2xyz(data, penh)

Evaluate the local x/y/'z'-positions of the given global positions penh (easting, northing, height) for data set data.

[pxyz, data] = crg_eval_llh2xyz(data, pllh)

Evaluate the local x/y/'z'-positions of the given geographic coordinates pllh(latitude, longitude, height) for data set data. data must have appropriate map projection data.

[penh, data] = crg_eval_xyz2enh(data, pxyz)

Evaluate the global map positions penh(easting, northing, height) of the given local x/y/'z'-positions-positions for data set data.

[pllh, data] = crg_eval_xyz2llh(data, pxyz)

Evaluate the geographic coordinates pllh (latitude, longitude, height) of the given local x/y/'z'-positions for data set data. data must have appropriate map projection data.

6.7.4. Examples

C examples

The following example shows how to evaluate z-values using the C-API.

double z;

/* load CRG file */
int dataSetId = crgLoaderReadFile( 'demo.crg' );

/* create contact point */
int cpId = crgContactPointCreate( dataSetId );

/* evaluate z at (u,v) = [100 0] */
crgEvaluv2z( cpId, 100, 0, &z );
MATLAB examples

The following example shows how to evaluate z-values using the MATLAB tools.

% load CRG file
data = crg_read('demo.crg');

% evaluate z at (u,v) = [100 0]
pz = crg_eval_uv2z(data, [100 0]);

6.8. Manipulating OpenCRG data

OpenCRG data is usually changed by applying modifiers or setting options. However, there are some changes that you cannot achieve with modifiers or options. An example is when you need to prepare real-world data for use in simulations.

The MATLAB tools cover the following use cases:

  • Appending or cutting OpenCRG data sets.

  • Extracting and changing slope and banking.

  • Filtering and limiting z-values.

  • Flipping road data or mapping it to different coordinate systems.

6.8.1. Prerequisites

  • You have loaded an OpenCRG data set.

6.8.2. Corresponding C functions

The C-API does not provide functions for manipulating OpenCRG data.

6.8.3. Corresponding MATLAB functions

[data, roff2] = crg_append(data1, data2)

Append an OpenCRG data set data2 to the OpenCRG data set data1 and return the resulting data set data. For a smooth connection, the second grid is re-positioned so that both grids overlap for one longitudinal increment. The re-positioned data set is returned as roff2. The last latitudinal cut of data and the first latitudinal cut of data2 are dropped. Incomplete or inconsistent WGS 84 values at the intersection result in omitting the WGS 84 information in the result.

[data] = crg_cut_iuiv(data, iu, iv)

Cut out a part of a OpenCRG road data. iu and iv specify the index positions of the area to be cut out.

[data] = crg_separate_sb(data, swlen, bwlen)

Find and filter slope and banking in road data of data. Slope and banking are filtered using a moving average with window lenght swlen and bwlen, respectively. Separate the filtered result from the road data leaving the total elevation information unchanged.

[data] = crg_b2z(data, b)

Apply new banking b to the OpenCRG data in data. Merge existing banking into the road data.

[data] = crg_s2z(data, rz)

Apply new slope defined by rz to the OpenCRG data in data. Merge existing slope into the road data.

[data] = crg_ext_slope(data, p)

Extract the slope from OpenCRG data in data. pp is a smoothing parameter.

[data] = crg_ext_banking(data, pp)

Extract the banking from OpenCRG data in data. pp is a smoothing parameter.

[data] = crg_filter(data, iu, iv, fm, mask, wopt)

Filter OpenCRG data in data. iu and iv can be used to limit filtering to an area of the grid. fm specifies the filtering method. mask specifies the size of the filter mask. The optional wopt defines filter weights and number of repeated filter applications.

[data] = crg_limiter(data, mmlim, iu, iv)

Limit z-values in data to the minimum and maximum defined in mmlim. iu and iv can be used to limit the operation to an area of the grid.

[data] = crg_wrap(data)

Wrap heading angles of road parameters and road data in data to a +/- pi range.

[data] = crg_flip(data)

Flip the OpenCRG data in data, swapping start and end while leaving the modifiers and options unchanged.

[data] = crg_map_uv2uv(data, crg_uv, iu, iv)

Map z-values of crg_uv in u/v-coordinates to the u/v-grid of data. iu and iv can be used to limit the operation to an area of the grid.

[data] = crg_map_xy2xy(data, crg_xy, iu, iv)

Map z-values of crg_xy in x/y-coordinates to the inertial x/y-coordinate system of data. iu and iv can be used to limit the operation to an area of the grid.

[data] = crg_rerender(crg, inc, v)

Re-render OpenCRG data in crg as data with new u/v-increment inc and v-spacing v.

6.8.4. Examples

MATLAB examples

The following example shows how to manipulate data using the MATLAB tools.

% load OpenCRG data
data = crg_read('demo.crg');

% extract banking with smoothing
exdata = crg_ext_banking(data, 0.0000000000003);

% extract slope
exdata = crg_ext_slope(exdata);

% visualize results
crg_show_refline_elevation(exdata);
crg_show_elgrid_surface(exdata)
crg_show_road_surface(exdata);

6.9. Generating OpenCRG data

With the MATLAB tools, you can generate synthetic OpenCRG data. You can define section-wise curvature, banking and slope independently by using polynomials of grade 2.

6.9.1. Prerequisites

None.

6.9.2. Corresponding C functions

The C-API does not provide functions for generating OpenCRG data.

6.9.3. Corresponding MATLAB functions

[data] = crg_gen_csb2crg0(inc, u, v, c, s, b)

Generate a synthetic OpenCRG struct data with a regular grid, curvature, slope, and banking. inc specifies the increments in both u-direction and v-direction. u and v specify the extend of the reference line. c specifies the curvature. s specifies the slope.

[data, err] = crg_gen_ppxy2phi(ppxy, uinc, opts)

Generate a partial OpenCRG struct data with reference line heading information by evaluating the given smooth polynomial ppxy in pp-form. uinc specifies the reference line increment. The optional struct opts specifies the discretization method, although the default method should be used in all cases. err contains the position error after forward integration.

[ppxy] = crg_gen_pxy2ppxy(pxy, opts)

Generate a smooth polynomial ppxy in pp-form from the given reference points pxy. The optional opts struct holds parameters for internal spline fit and spline smoothing functions.

[v] = crg_check_uv_descript(uv_descript, posmode)

Check whether the uv-description uv_descript is in a valid form and generate the associated v-profile v.

6.9.4. Examples

MATLAB examples
% minimal grid setup
u =   [  0    900   ];
v =   [ -2.50   2.5 ];
inc = [  0.04   0.02];

% generate synthetical straight OpenCRG data
data = crg_gen_csb2crg0(inc, u, v);

% add z-values
[nu nv] = size(data.z);

z = 0.01*peaks(nv);
z = repmat(z, ceil(nu/nv), 1);

data.z(1:nu,:) = single(z(1:nu,:));

For more elaborate examples, see the MATLAB demo files.

6.10. Visualizing OpenCRG data

The C-API does not provide functions for visualizing OpenCRG data. However, the C-API provides some methods for displaying information about an OpenCRG data set.

The MATLAB tools provide a large collection of functions for visualizing OpenCRG data. crg_show() creates several figures visualizing different aspects of an OpenCRG data set. You can create each of these figures individually by calling the respective crg_show_*() function. These figures use subplots themselves. You can create each of these plots individually by calling the respective crg_plot_*() function.

6.10.1. Prerequisites

  • You have loaded an OpenCRG data set.

  • You have set and applied modifiers.

  • You have set options.

6.10.2. Corresponding C functions

void crgDataPrintHeader( int dataSetId )

Print the header information of dataSetId.

void crgDataPrintChannelInfo( int dataSetId )

Print information about the channels in dataSetId.

void crgDataPrintRoadInfo( int dataSetId );

Print information about the road in dataSetId.

6.10.3. Corresponding MATLAB functions

[data] = crg_show(data, iu, iv)

Create several figures visualizing different aspects of OpenCRG data in data. iu and iv can be used to limit the plots to a part of the grid.

[data] = crg_show_refline_map(data, iu)

Visualize the reference line defined in data in a figure with several subplots. iu can be used to limit the plots to a range on the reference line.

[data] = crg_show_refpnts_and_refline(data, pxy)

Visualize the reference points in pxy in relation to the reference line in data.

[data] = crg_show_refline_elevation(data, iu)

Visualize the z-values in data along the reference line defined in data in a figure with several subplots. iu can be used to limit the plots to a range on the reference line.

[data] = crg_show_elgrid_cuts_and_limits(data, iu, iv)

Visualize the z-values in data as longitudinal and latitudinal cuts as well as the outer limits of the grid. iu and iv can be used to limit the plots to a part of the grid.

[data] = crg_show_road_surface(data, iu, iv)

Visualize the z-values in data via orthographic images and three-dimensional surface plots. iu and iv can be used to limit the plots to a part of the grid.

[data] = crg_show_road_surface(data, iu, iv)

Visualize the road surface described in data via orthographic images and three-dimensional surface plots. iu and iv can be used to limit the plots to a part of the grid.

[data] = crg_show_road_uv2surface(data, u, v)

Visualize the road surface described in data via orthographic images and three-dimensional surface plots on a grid given by the vectors u and v.

[data] = crg_show_info(data)

Display information about data in a text box.

[ ] = crg_show_isequal(dd, out)

Visualize dd, the result of comparing two OpenCRG files. dd is usually the return value of crg_isequal(). out can be set to html to publish the result as HTML.

[data] = crg_show_peaks(data, pindex, su, sv, iu, iv)

Visualize peaks at pindex in data. pindex is usually the return value of crg_peakfinder(). su and sv can be used to limit the visualization of peaks to a part of the grid. iu and iv can be used to limit the plots to a part of the grid.

[data] = crg_plot_refline_xy_overview_map(data, iu)

Plot the reference line using x/y-coordinates. iu can be used to limit the plots to a range on the reference line.

[data] = crg_plot_refline_curvature(data, iu)

Plot curvature along the reference line in data. iu can be used to limit the plots to a range on the reference line.

[data] = crg_plot_refline_elevation(data, iu)

Plot z-values along the reference line in data. iu can be used to limit the plots to a range on the reference line.

[data] = crg_plot_refline_heading(data, iu)

Plot the heading angle along the reference line of data. iu can be used to limit the plots to a range on the reference line.

[data] = crg_plot_refline_slope_bank(data, iu)

Plot slope and banking along the reference line of data. iu can be used to limit the plots to a range on the reference line.

[data] = crg_plot_refline_xyz_map(data, iu)

Plot the reference line using x/y/z-coordinates. iu can be used to limit the plots to a range on the reference line.

[data] = crg_plot_refline_xy_map_and_curv(data, iu)

Plot the reference line using x/y-coordinates as well as its curvature. iu can be used to limit the plots to a range on the reference line.

[data] = crg_plot_elgrid_limits(data, iu, iv)

Plot the outer limits of the data in data in the current axis object. iu and iv can be used to limit the plots to a part of the grid.

[data] = crg_plot_elgrid_cross_sect(data, iu, iv)

Plot z-values of data over v for various u-coordinates. iu and iv can be used to limit the plots to a part of the grid.

[data] = crg_plot_elgrid_long_sect(data, iu, iv)

Plot z-values of data over u for various v-coordinates. iu and iv can be used to limit the plots to a part of the grid.

[data] = crg_plot_elgrid_uvz_map(data, iu, iv)

Plot z-values in data as orthographic image over an uncurved grid using u/v-coordinates. iu and iv can be used to limit the plots to a part of the grid.

[data] = crg_plot_elgrid_xyz_map(data, iu, iv)

Plot z-values in data as three-dimensional image over a curved grid using x/y-coordinates. iu and iv can be used to limit the plots to a part of the grid.

[data] = crg_plot_refpnt_distances(data, pxy)

Plot the distance of a series of reference points pxy to the reference line described in data. The reference points use x/y-coordinates.

[data] = crg_plot_road_uvz_map(data, iu, iv)

Plot the road surface in data as orthographic image over an uncurved grid. iu and iv can be used to limit the plots to a part of the grid.

[data] = crg_plot_road_xyz_map(data, iu, iv)

Plot the road surface in data as three-dimensional image over a curved grid. iu and iv can be used to limit the plots to a part of the grid.

[data] = crg_plot_road_uv2uvz_map(data, u, v)

Plot the road surface in data as orthographic image over an uncurved grid given by the vectors u and v.

[data] = crg_plot_road_uv2xyz_map(data, u, v)

Plot the road surface in data as three-dimensional image over a curved grid given by the vectors u and v.

[data] = crg_surf(data, x, y, z)

Create a three-dimensional surface plot of z over x and y using figure options defined in data.

[data] = crg_figure(data)

Set up an OpenCRG figure using the figure options in data.fopt.

[ ] = copy_ax2fig()

Copy the current axis object to a new figure. This function is most useful if called by a mouse-click action in a subplot of a complex figure.

6.10.4. Examples

MATLAB examples
% load CRG file
data = crg_read('demo.crg');

%% visualize the entire road
crg = crg_show(data);

6.11. Mapping OpenCRG data to geographical positions

The C-API does not provide functions for handling geographical coordinates. Instead, the C-API ignores any data associated with map projections.

The MATLAB tools provide a large collection of functions for visualizing, converting and transforming geographic data. Overview of coordinate transformations. shows the available coordinate systems and transformations. Many of these functions are generic and may also be used for data not in OpenCRG format.

transformations
Figure 5. Overview of coordinate transformations.

Map projection data can be defined either in the OpenCRG file or by accessing the relevant fields of the loaded OpenCRG data.

6.11.1. Prerequisites

  • You have loaded an OpenCRG data set.

  • The OpenCRG data contains the required map projection data.

6.11.2. Corresponding C functions

The C-API does not provide functions for visualizing OpenCRG data.

6.11.3. Corresponding MATLAB functions

map_intro[]

Display introductory information on handling geographic data.

[data] = crg_wgs84_crg2html(data, file, opts)

Generate a HTML file file to display OpenCRG data data as a track in a web-based map using OpenLayers. opts contains various options for changing the generated HTML file.

[file] = map_wgs2html(llh, file, opts)

Generate a HTML file file to display WGS 84 positions llh as a track in a web-based map using OpenLayers. opts contains various options for changing the generated HTML file.

[enh ell pro] = map_geod2pmap(llh, ell, pro)

Convert points llh from geodetic coordinates to map coordinates using a forward projection. An ellipsoid struct ell and a map projection struct pro may be optionally provided.

[enh ell pro] = map_geod2pmap_tm(llh, ell, pro)

Convert points llh from geodetic coordinates to map coordinates using forward transverse Mercator projection. An ellipsoid struct ell and a map projection struct pro may be optionally provided.

[llh ell pro] = map_pmap2geod_tm(enh, ell, pro)

Convert points enh from map coordinates to geodetic coordinates llh using backward transverse Mercator projection. An ellipsoid struct ell and a map projection struct pro may be optionally provided.

[xyz ell] = map_geod2ecef(llh, ell)

Convert points llh from a geodetic system to ECEF system. An ellipsoid struct ell may be optionally provided.

[xyzb tran] = map_ecef2ecef(xyza, tran, fwbw)

Transforms points xyza from one ECEF datum to another. A transformation struct tran specifying the transformation may be optionally provided. The optional fwbw flag specifies, whether to use forward or backward transformation.

[llh ell] = map_ecef2geod(xyz, ell)

Convert points from a ECEF system to a geodetic system. An ellipsoid struct ell may be optionally provided.

[enh dat] = map_global2plocal(llh, dat)

Convert points from global geodetic coordinates llh to local map coordinates enh by transforming from global to local ellipsoid and forward projection on local ellipsoid. dat contains information necessary for the conversion.

[llh dat] = map_plocal2global(enh, dat)

Convert points from local map coordinates enh to global geodetic coordinates llh by backward projection on a local ellipsoid and datum transformation from a local to global ellipsoid. dat contains information necessary for the conversion.

[phi ell pro] = map_ptm_north2initiallat(north, ell, pro)

Compute the initial latitude values phi for given northings north. Utility function needed for transverse Mercator projections.

[marc ell pro] = map_ptm_phi2marc(phi, ell, pro)

Compute the meridional arc marc for given latitudes phi. Utility function needed for transverse Mercator projections.

[dat] = map_check(dat)

Check and update dat as used in map_global2plocal and map_plocal2global.

[ell] = map_check_elli(ell)

Check and update ellipsoid struct ell.

[pro] = map_check_proj(pro)

Check and update map projection struct pro.

[tran] = map_check_tran(tran)

Check and update datum transformation struct tran.

[url] = crg_wgs84_wgs2url(wgs, opts)

Generate a URL url for showing WGS 84 coordinates wgs using Google Maps. opts.label contains a label for the positions.

[wgs, data] = crg_wgs84_xy2wgs(data, pxy)

Transform points pxy given in local x/y-coordinates to WGS 84 coordinates wgs using the provided OpenCRG data data as reference.

[wgs] = crg_wgs84_wgsxy2wgs(wgs1, wgs2, pxy1, pxy2, pxy, eps, tol, dmin)

Transforms points pxy given in local x/y-coordinates to WGS 84 coordinates. This transformation uses two reference points. These reference points are passed to the function using both WGS 84 coordinates (wgs1, wgs2) and local x/y-coordinates (pxy1, pxy2). eps, tol and dmin define requirements for numerical consistency.

[dist dbeg dend] = crg_wgs84_dist(wgs1, wgs2)

Evaluate the distances dist and bearings dbeg and dend between the WGS 84 positions in wgs1 and wgs2. dbeg is the bearing as seen from wgs1. dend is the bearing as seen from wgs2.

[wgs2 dend] = crg_wgs84_invdist(wgs1, dbeg, dist)

Calculate WGS 84 positions wgs2 defined by a WGS 84 base position wgs1, a bearing dbeg, and a distance dist. dend is the bearing as seen from wgs2.

[data] = crg_wgs84_setend(data, dref)

Set missing WGS 84 end coordinate with given beginning-to-end direction for the reference line.

6.11.4. Examples

MATLAB examples

The following example shows the conversion of WGS 84 coordinates to UTM coordinates. As the example position is located Bavaria, Germany, the grid zone is 32U. Both UTM and WGS 84 use the same ellipsoid. Thus, a datum transformation is not required.

% example position ASAM e.V.
% (Altlaufstraße 40, 85635 Höhenkirchen-Siegertsbrunn)
org_llh = [	48.02331, 11.71584, 584.0]; % WGS 84

% create mpro
mpro.gell.nm='WGS84';   % global datum
mpro.proj.nm='UTM_32U'; % map projection including local datum

% WGS 84 llh degree -> WGS 84 llh radian
llh = [pi/180*org_llh(1), pi/180*org_llh(2), org_llh(3)];

% transform WGS 84 llh radian -> UTM_32U
enh_utm = map_geod2pmap_tm(llh, mpro.gell, mpro.proj)

The following example shows the conversion WGS 84 coordinates to GK3 coordinates. As the example position is located Bavaria, Germany, the zone number is 4. A datum transformation is required, because GK3 uses the BESSELDHDN ellipsoid, which is different from the WGS 84 ellipsoid.

% example position ASAM e.V.
% (Altlaufstraße 40, 85635 Höhenkirchen-Siegertsbrunn)
org_llh = [	48.02331, 11.71584, 584.0]; % WGS 84

% create mpro
mpro.gell.nm='WGS84';
mpro.lell.nm='BESSELDHDN';
mpro.proj.nm='GK3_4';
mpro.tran.nm='HN7';     % transformation
% 7 Parameter Helmert transformation (example for Bavaria from LDBV)
mpro.tran.ds = -5.2379 * 0.000001;
mpro.tran.rx = (0.7201 / 3600) * (pi / 180);
mpro.tran.ry = (0.1112 / 3600) * (pi / 180);
mpro.tran.rz = (-1.7209 / 3600) * (pi / 180);
mpro.tran.tx = -604.7365;
mpro.tran.ty = -72.3946;
mpro.tran.tz = -424.402;
mpro=map_check(mpro);

% WGS 84 llh degree -> WGS 84 llh radian
llh = [pi/180*org_llh(1), pi/180*org_llh(2), org_llh(3)];

% transform WGS 84 llh radian -> GK3 zone 4 (BESSELDHDN)
% transformation includes datum transformation, see map_global2plocal.m
enh_gk = map_global2plocal(llh, mpro)

6.12. Checking OpenCRG data

OpenCRG data can contain inconsistent definitions, for example, definitions in the road parameters section that do not match the actual data in the road data section. Checking OpenCRG data ensures internal consistency, accuracy, and completeness.

Another example are intersecting lateral cuts caused by high curvature, resulting in an ambiguous grid definition. A global curvature check fails if two or more lateral cuts intersect inside the road limits. In this case, the local curvature check still succeeds, if such an intersection falls into a region of NaN values.

With the C-API, OpenCRG data is not checked automatically upon reading. It must be checked explicitly via an appropriate API call.

Most functions of the MATLAB tools already call crg_check internally. With the MATLAB tools, it is usually not required to check OpenCRG data explicitly.

6.12.1. Prerequisites

  • You have loaded an OpenCRG data set.

6.12.2. Corresponding C functions

int crgCheck( int dataSetId )

Check OpenCRG data dataSetId for consistency and accuracy and returns true if the data was checked successfully. Check reference line curvature in dataSetId globally and locally, if the respective options are set.

6.12.3. Corresponding MATLAB functions

[data] = crg_check(data)

Run all available checks on the OpenCRG data in data.

[data] = crg_check_opts(data)

Check OpenCRG options in data for consistent definitions and values.

[data] = crg_check_mods(data)

Check OpenCRG modifiers in data for consistent definitions and values. Provide missing defaults.

[data] = crg_check_head(data)

Check OpenCRG road parameters in data for consistent definitions and values.

[data] = crg_check_mpro(data)

Check OpenCRG map projection data in data for consistent definitions and values.

[data] = crg_check_data(data)

Check OpenCRG data in data for consistency and accuracy, fix minor accuracy problems, and complement and condense the OpenCRG data as far as possible.

[data, ierr] = crg_check_curvature(data, ierr)

Check reference line curvature in data globally. Check reference line curvature in data locally, if the respective option is set.

[data] = crg_check_single(data)

Check whether OpenCRG data in core data vectors and arrays of data is of type single.

[data] = crg_check_wgs84(data)

Check whether the start position and the end position in data are consistently defined in both x/y/z-coordinates and WGS 84 coordinates.

6.12.4. Examples

C examples

The following example shows how to check OpenCRG data using the C-API.

/* load CRG file */
int dataSetId = crgLoaderReadFile( 'demo.crg' );

if ( !crgCheck( dataSetId ) )
{
    crgMsgPrint ( dCrgMsgLevelFatal, "main: could not validate OpenCRG data. \n" );
    return -1;
}
MATLAB examples

The following example shows how to check OpenCRG data explicitly using the MATLAB tools.

% load CRG file
data = crg_read('demo.crg');

%% check data
data = crg_check(data);

6.13. Writing OpenCRG files

With the MATLAB tools, you can create OpenCRG files from OpenCRG data in memory. These files use KRBI or LRFI format. Therefore, road data must be converted to type single before writing it to file.

6.13.1. Prerequisites

  • You have loaded or generated an OpenCRG data set.

The C-API does not provide functions for writing OpenCRG data.

[ier] = crg_write(data, file, type)

Write the OpenCRG data in data to the OpenCRG file file. By default, the file uses the KRBI format. The optional argument type may be used to specify LRFI format instead. Therefore, road data must be converted to type single first. ier indicates whether any errors occurred while writing the file.

[data] = crg_single(data)

Convert road data in data to type single.

6.13.4. Examples

MATLAB examples

The following example shows how to write the OpenCRG data in data to a KRBI file using the MATLAB tools.

% write CRG file
ier = crg_write(crg_single(data), 'demo.crg');