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:
Provision | Verbal form |
---|---|
Requirement |
shall |
Recommendation |
should |
Permission |
may |
Possibility and capability |
can |
Obligation and necessity |
must |
2.4.4. Typographic conventions
This documentation uses the following typographical conventions:
Mark-up | Definition |
---|---|
|
This format is used for code elements, such as technical names of classes and attributes, as well as attribute values. |
|
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. |
|
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.
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.
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.
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..
Data section | Keyword | Content | Remark |
---|---|---|---|
Header information |
|
Unstructured description in plain-text |
Mandatory |
Road parameter |
|
Structured definition of reference line in plain text |
Mandatory if file contains a road data section. |
Map projection data |
|
Structured definition of data for mapping OpenCRG data to geographic positions |
Optional |
Data definition |
|
Structured definition of data channels in plain text |
Mandatory if file contains a road data section. |
Options |
|
Structured definition of evaluation options in plain text |
Optional |
Modifiers |
|
Structured definition of data set modifiers in plain text |
Optional |
File reference |
|
References to other OpenCRG files in plain text |
Optional |
Road data |
none |
Actual road surface data in plain text or binary format. |
Optional |
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 |
---|---|---|
|
Double-precision floating-point number (default: 0.0) |
u-coordinate of start position. |
|
Double-precision floating-point number (default: calculated from road data) |
u-coordinate of end position. |
|
Double-precision floating-point number (default: none) |
Distance between lateral cross sections. |
|
Double-precision floating-point number (default: calculated from road data) |
v-coordinate of the outer right border of the road. |
|
Double-precision floating-point number (default: calculated from road data) |
v-coordinate of the outer left border of the road. |
|
Double-precision floating-point number (default: calculated from road data) |
Distance between axial cross sections. |
|
Double-precision floating-point number (default: 0.0) |
Slope at start position. |
|
Double-precision floating-point number (default: 0.0) |
Slope at end position. |
|
Double-precision floating-point number (default: 0.0) |
Banking at start position. |
|
Double-precision floating-point number (default: 0.0) |
Banking at end position. |
|
Double-precision floating-point number (default: 0.0) |
x-coordinate of start position of the reference line. |
|
Double-precision floating-point number (default: 0.0) |
y-coordinate of start position of the reference line. |
|
Double-precision floating-point number (default: calculated from road data) |
x-coordinate of end position of the reference line. |
|
Double-precision floating-point number (default: calculated from road data) |
y-coordinate of end position of the reference line. |
|
Double-precision floating-point number (default: 0.0) |
Global offset for x-coordinates. |
|
Double-precision floating-point number (default: 0.0) |
Global offset for y-coordinates. |
|
Double-precision floating-point number (default: 0.0) |
Heading angle at start position. |
|
Double-precision floating-point number (default: 0.0) |
Heading angle at end position. |
|
Double-precision floating-point number (default: 0.0) |
Global offset for heading angle. |
|
Double-precision floating-point number (default: 0.0) |
Elevation at start position. |
|
Double-precision floating-point number (default: 0.0) |
Elevation at end position. |
|
Double-precision floating-point number (default: 0.0) |
Global offset for elevation. |
|
Double-precision floating-point number |
Longitude of the start position in WGS 84 coordinates. |
|
Double-precision floating-point number |
Latitude of start position in WGS 84 coordinates. |
|
Double-precision floating-point number |
Longitude of end position in WGS 84 coordinates. |
|
Double-precision floating-point number |
Latitude of end position in WGS 84 coordinates. |
|
Double-precision floating-point number |
Altitude of start position in WGS 84 coordinates. |
|
Double-precision floating-point number |
Altitude of end position in WGS 84 coordinates. |
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 |
---|---|---|
|
Double-precision floating-point number (default: 0.0) |
Semi-major axis of user-defined global ellipsoid. |
|
Double-precision floating-point number (default: gell_a) |
Semi-minor axis of user-defined global ellipsoid. |
|
|
Identifier of the global ellipsoid. |
|
|
Identifier of datum transformation type.
|
|
Double-precision floating-point number (default: 0.0) |
Helmert transformation parameter: scalar scaling factor minus one ( |
|
Double-precision floating-point number (default: 0.0) |
Helmert transformation parameter: rotation around the x-axis. |
|
Double-precision floating-point number (default: 0.0) |
Helmert transformation parameter: rotation around the y-axis. |
|
Double-precision floating-point number (default: 0.0) |
Helmert transformation parameter: rotation around the z-axis. |
|
Double-precision floating-point number (default: 0.0) |
Helmert transformation parameter: translation along the x-axis. |
|
Double-precision floating-point number (default: 0.0) |
Helmert transformation parameter: translation along the y-axis. |
|
Double-precision floating-point number (default: 0.0) |
Helmert transformation parameter: translation along the z-axis. |
|
Double-precision floating-point number (default: 0.0) |
Semi-major axis of the local ellipsoid. |
|
Double-precision floating-point number (default: lell_a) |
Semi-minor axis of the local ellipsoid. |
|
|
Identifier of the local ellipsoid. |
|
GK3_0 … GK3_119, GK6_0 … GK6_59, UTM_01C … UTM_60X, TM_0 … TM_359, TM |
Identifier of the map projection
|
|
Double-precision floating-point number (default: 1.0) |
Map projection parameter: center meridian scaling. |
|
Double-precision floating-point number (default: 0.0) |
Map projection parameter: latitude of origin. |
|
Double-precision floating-point number (default: 0.0) |
Map projection parameter: longitude of origin. |
|
Double-precision floating-point number (default: 0.0) |
Map projection parameter: false easting. |
|
Double-precision floating-point number (default: 0.0) |
Map projection parameter: false northing. |
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.
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 |
---|---|
|
Binary data format using numbers of type real |
|
Binary data format using numbers of type double |
|
Human-readable plain-text format using numbers of type real |
|
Human-readable plain-text format using numbers of type double |
|
Data entries represent heading angles of the reference line in rad. |
|
Data entries represent banking as dimensionless fraction. |
|
Data entries represent slope as dimensionless fraction. |
|
Data entries represent a longitudinal cut at position X in meters. X corresponds to a v-coordinate. |
|
Data entries represent the X-th longitudinal cut. To use this definition, both the width of the road and the increments in v-direction must be defined in the road parameters section. |
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 |
---|---|---|
|
0, 1, 2, 3, 4 (default: 2) |
Returned z-value, when a query exceeds the beginning or the end of the road.
|
|
0, 1, 2, 3, 4 (default: 2) |
Returned z-value, when a query exceeds the left side or the right side of the road.
|
|
Double-precision floating-point number (default: 0.0) |
Offset for returned z-value, when a query exceeds the beginning or the end of the road. |
|
Double-precision floating-point number (default: 0.0) |
Offset for returned z-value, when a query exceeds the left side or the right side of the road. |
|
Double-precision floating-point number from 0.0 to umax (default: 0.0) |
Range for scaling z-values linearly from 0 to the actual value, including slope and banking. Provides a smooth increase of road data at the beginning of the road. |
|
Double-precision floating-point number from 0.0 to umax (default: 0.0) |
Range for scaling z-values linearly from the actual value to 0. Provides a smooth decrease of road data at the end of the road. |
|
0, 1 (default: 0) |
Mode for computing x/y-positions if a given u-coordinate is positioned outside the defined reference line.
|
|
-1, 0, [1;∞[ (default: -1) |
Number of warning messages displayed.
|
|
0, 1 (default: 0) |
Check whether local curvature limit is exceeded.
|
|
0, 1 (default: 0) |
Check whether global curvature limit is exceeded.
|
|
[1e-6; 1e-2] (default: 1e-6) |
Expected minimal accuracy, used for numerical consistency checks. |
|
less than 0.001*(1-CHECK_EPS) or abs(round(CHECK_INC=0.001 * (1-CHECK_EPS)) 0.001 * (1-CHECK_EPS) * CHECK_INC) > CHECK_EPS * max(0.001 * (1-CHECK_EPS); CHECK_INC) (default: 1e-3) |
Expected minimum increment, used for numerical consistency checks. |
|
[CHECK_EPS*CHECK_INC; 0.5*CHECK_INC] (default: 0.1*CHECK_INC) |
Expected absolute tolerance, used for numerical consistency checks. |
|
[0.1*CHECK_INC; 1] (default: 5e-3) |
Expected projection tolerance, used for numerical consistency checks. |
|
[0.1*CHECK_INC; 1000] (default: 10) |
Expected WGS 84 tolerance, used for numerical consistency checks. |
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 |
---|---|---|
|
Double-precision floating-point number |
u-coordinate of reference point for relocating by reference point. |
|
Double-precision floating-point number |
v-coordinate of reference point for relocating by reference point. |
|
Double-precision floating-point number: [0.0, 1.0] (default: 0.0) |
Relative u-coordinate of reference point for relocating by reference point. |
|
Double-precision floating-point number (default: 0.0) |
Offset for u-coordinate of reference point for relocating by reference point. |
|
Double-precision floating-point number: [0.0, 1.0] (default: 0.0) |
Relative v-coordinate of reference point for relocating by reference point. |
|
Double-precision floating-point number (default: 0.0) |
Offset for v-coordinate of reference point for relocating by reference point. |
|
Double-precision floating-point number (default: 0.0) |
x-coordinate of target position for relocating by reference point. |
|
Double-precision floating-point number (default: 0.0) |
y-coordinate of target position for relocating by reference point. |
|
Double-precision floating-point number (default: 0.0) |
z-coordinate of target position for relocating by reference point. |
|
Double-precision floating-point number (default: 0.0) |
Absolute heading angle of target position for relocating by reference point. |
|
Double-precision floating-point number (default: x-coordinate of starting position) |
x-coordinate of rotation center for relocating by rotation and translation. |
|
Double-precision floating-point number (default: y-coordinate of starting position) |
y-coordinate of rotation center for relocating by rotation and translation. |
|
Double-precision floating-point number (default: 0.0) |
Rotation angle for re-locating by rotation and translation. |
|
Double-precision floating-point number (default: 0.0) |
Offset in x-direction for relocating by rotation and translation. |
|
Double-precision floating-point number (default: 0.0) |
Offset in y-direction for relocating by rotation and translation. |
|
Double-precision floating-point number (default: 0.0) |
Offset in z-direction for relocating by rotation and translation. |
|
Double-precision floating-point number (default: 0.0) |
Factor for scaling the data in z-direction. |
|
Double-precision floating-point number (default: 0.0) |
Factor for scaling slope in elevation data. |
|
Double-precision floating-point number (default: 0.0) |
Factor for scaling banking in elevation data. |
|
Double-precision floating-point number: ]0.0,∞] (default: 0.0) |
Factor for scaling the data in u-direction. |
|
Double-precision floating-point number: ]0.0,∞] (default: 0.0) |
Factor for scaling the data in v-direction. |
|
Double-precision floating-point number: : [0.0,∞] (default: 0.0) |
Factor for scaling the curvature. |
|
0, 1, 2 |
Mode for replacing NaN values in road data borders.
|
|
Double-precision floating-point number (default: 0.0) |
Offset applied to replaced NaN values. |
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.
$ROAD_CRG_MODS REFLINE_ROTCENTER_X = 0 ! rotation center at x = 0 REFLINE_ROTCENTER_Y = 0 ! rotation center at y = 0 REFLINE_OFFSET_PHI = 1.57 ! rotated by 1.57 rad (90°) REFLINE_OFFSET_Z = 100 ! shift 100 m in x-direction REFLINE_OFFSET_Y = 100 ! shift 100 m in y-direction REFLINE_OFFSET_Z = 100 ! shift 100 m in z-direction $!************************
The following example illustrates how NaN values at the border can be replaced by an arbitrary value (here: 10 m).
$ROAD_CRG_MODS GRID_NAN_MODE = 1 ! replace NaN with z = 0 GRID_NAN_OFFSET = 10 ! offset former NaN values by 10 m $!************************
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
/home/name/crg-files/handmade_straight.crg
/home/name/crg-files/hand made_straight.crg
./handmade_straight.crg
$crgpath/handmade_straight.crg
$ROAD_CRG_FILE /home/name/crg-files/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.
$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
-
Navigate to the Download area.
-
Follow the instructions to download the software package.
-
Download the ZIP archive.
-
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
-
Open a command line interpreter.
-
Change to the
c-api
directory. -
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.
Related topics
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
-
Open the shell script
c-api/compileScript.sh
in a text editor. -
Find the variable
COMP
and set it to the name of your compiler. -
Save your changes to the script.
-
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.
Related topics
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.
Related topics
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
-
To run all tests for evaluation options, execute the script
c-api/test/bin/testOptions.sh
. -
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
-
Open a command line interpreter.
-
Switch to the directory containing the executable of the sample program. The executables are stored in
open-crg/c-api/demo/bin/
. -
Run
[program] -help
to display information about the available options. -
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:
Filename | Description |
---|---|
|
Transform points in e/n/h to x/y/z. |
|
Transform points in llh to x/y/z. |
|
Evaluate curvature at reference line positions. |
|
Evaluate heading angles at reference line positions. |
|
Evaluate index positions of grid positions. |
|
Evaluate local coordinates of grid positions. |
|
Evaluate z at grid position. |
|
Transform points in x/y to u/v. |
|
Evaluate z at x/y-position. |
|
Transform point in x/y/z to e/n/h. |
|
Transform point in x/y/z to l/l/h. |
Filename | Description |
---|---|
|
Copy current axes object to new figure. |
|
Set up OpenCRG figure. |
|
Compare two OpenCRG data sets. |
|
Detect peaks in a OpenCRG data. |
|
Plot z-values over latitudinal cuts. |
|
Plot the outer grid limits. |
|
Plot z-values over longitudinal cuts. |
|
Plot z-values as uncurved orthographic image. |
|
Plot z-values as curved three-dimensional image. |
|
Plot curvature along the reference line. |
|
Plot the z-values along the reference line. |
|
Plot heading angle along the reference line. |
|
Plot slope and banking along the reference line. |
|
Plot reference line in x/y/z-coordinates. |
|
Plot reference line including curvature. |
|
Plot reference line in x/y-coordinates. |
|
Plot distance of reference points to reference line. |
|
Plot road surface over a given uncurved grid. |
|
Plot road surface over a given curved grid. |
|
Plot road surface as uncurved orthographic image. |
|
Plot road surface as curved three-dimensional image. |
|
Visualize CRG data. |
|
Visualize the cuts and limits of the CRG |
|
Visualize z-values. |
|
Display information about the CRG. |
|
Visualize the result of comparing two OpenCRG files. |
|
Visualize peaks. |
|
Visualize elevation along the reference line. |
|
Visualize the reference line. |
|
Visualize reference points and reference line. |
|
Visualize the road surface. |
|
Visualize the road surface on a given grid. |
|
Plot a three-dimensional surface. |
Filename | Description |
---|---|
|
Read OpenCRG file. |
|
Convert OpenCRG road data to type single. |
|
Wrap heading angles to +/- pi range. |
|
Write OpenCRG file. |
|
IPLOS write/read demonstration. |
|
Read IPLOS file. |
|
Write IPLOS file. |
|
Add block to struct data file. |
|
Cut block from struct data file. |
|
Convert number to string of given length. |
Filename | Description |
---|---|
|
Run all OpenCRG data checks. |
|
Check OpenCRG curvature data. |
|
Check, fix, and complement OpenCRG data. |
|
Check OpenCRG road parameters data. |
|
Check modifier data. |
|
Check OpenCRG map projection data. |
|
Check OpenCRG options data. |
|
Check core OpenCRG data for type single. |
|
Check OpenCRG WGS 84 data. |
Filename | Description |
---|---|
|
Append a second compatible OpenCRG to a first OpenCRG. |
|
Apply banking to OpenCRG data. |
|
Cut out a part of a OpenCRG road. |
|
Extract banking from OpenCRG data. |
|
Extract slope from OpenCRG data. |
|
Apply filter to OpenCRG data. |
|
Flip OpenCRG data. |
|
Limits z-values in OpenCRG data. |
|
Map z-values from one grid to another. |
|
Map z-values from one local coordinate system to another. |
|
Apply modifiers to data. |
|
Re-render OpenCRG data for a new u/v-grid. |
|
Apply slope to OpenCRG data. |
|
Separate slope and banking. |
|
Smooth input signals with symmetric FIR filter. |
Filename | Description |
---|---|
|
Check uv_descript and create a v-profile. |
|
Generate synthetic OpenCRG data. |
|
Generate reference line heading from polynomial. |
|
Generates smooth polynomial from reference points. |
|
Generate synthetical surface. |
Filename | Description |
---|---|
|
Generate HTML file to visualize OpenCRG data in a map. |
|
Evaluate distance and bearing between WGS 84 positions. |
|
Calculate WGS 84 positions by distance and bearing. |
|
Set WGS 84 end coordinate. |
|
Generate URL to show WGS 84 information on Google Maps |
|
Transform points in x/y-coordinates to WGS 84 coordinates using two references. |
|
Transform points in x/y-coordinates to WGS 84 coordinates. |
|
Check and update DAT struct. |
|
Check and update ellipsoid struct. |
|
Check and update map projection struct. |
|
Check and update datum transformation struct. |
|
Datum transformation in ECEF system. |
|
Convert points from ECEF system to geodetic system. |
|
Convert points from geodetic system to ECEF system. |
|
Forward map projection. |
|
Forward transverse Mercator projection. |
|
Forward projection: global to projected local. |
|
MAP routines introduction |
|
Backward projection: projected local to global. |
|
Backward projection: transverse Mercator. |
|
Transverse Mercator utility function. |
|
Transverse Mercator utility function: meridional arc. |
|
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
-
In MATLAB, switch to the Command Window.
-
Run
run path-to-opencrg/matlab/crg_init
to add the MATLAB tools to the MATLAB search path. -
Run
mkdir path-to-opencrg/matlab/temp
to create a directory for temporary data. -
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.
Related topics
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
-
In MATLAB, switch to the Command Window.
-
To get an overview of the MATLAB implementation, run
crg_intro
. -
To get help for a specific function, run
help function
.
Result
The help text is displayed in the Command Window.
Related topics
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
-
Run
crg_demo
to create the required OpenCRG data structures and write them to file. -
Run
crg_demo_demoname
, to run the demo of the respective name. -
Run
crg_test_testname
, to run the test of the respective name.
Related topics
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.
6.3.1. Related C functions
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
.
6.3.2. Related MATLAB functions
[data] = crg_read(file)
-
Read the OpenCRG file
file
and returns a structure arraydata
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.3.4. Related topics
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 setdataSetId
to the valuemodValue
. int crgDataSetModifierSetDouble( int dataSetId, unsigned int modId, double modValue )
-
Set the double modifier
modId
of the data setdataSetId
to the valuemodValue
. int crgDataSetModifierGetInt( int dataSetId, unsigned int modId, int* modValue )
-
Get the current value of the integer modifier
modID
of the data setdataSetId
and store it inmodValue
. 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 setdataSetId
and store it inmodValue
. int crgDataSetModifierRemove( int dataSetId, unsigned int modId )
-
Remove the modifier
modID
from the data setdataSetId
. 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 indata
. Afterwards, remove all modifiers fromdata.mods
. Ifdata.mods
does not exist, default modifier values are applied. Ifdata.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.4.5. Related topics
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 setdataSetId
. 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.5.5. Related Topics
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 pointcpId
to the valueoptionValue
. int crgContactPointOptionSetDouble( int cpId, unsigned int optionId, double optionValue )
-
Set the double option
optionId
of the contact pointcpId
to the valueoptionValue
. int crgContactPointOptionGetInt( int cpId, unsigned int optionId, int* optionValue )
-
Get the current value of the integer option
optionId
of the contact pointcpId
and store it inoption value
. int crgContactPointOptionGetDouble( int cpId, unsigned int optionId, double* optionValue )
-
Get the current value of the double option
optionId
of the contact pointcpId
and store it inoption 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 pointcpId
. 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.6.5. Related topics
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 givenu
/v
-position for contact pointcpId
. void crgEvalxy2z( int cpId, double u, double v, double* z )
-
Evaluate the
z
-value at a givenx
/y
-position for contact pointcpId
. void crgEvaluv2xy( int cpId, double u, double v, double* x, double* y )
-
Evaluate the
x
/y
-position of a givenu
/v
-position for contact pointcpId
. void crgEvalxy2uv( int cpId, double x, double y, double* u, double* v )
-
Evaluate the
u
/v
-position of a givenx
/y
-position for contact pointcpId
. void crgEvaluv2pk( int cpId, double u, double v, double* phi, double* crv )
-
Evaluate the heading angle
phi
and the curvaturecrv
at a givenu
/v
-position for contact pointcpId
. int crgEvalxy2pk( int cpId, double x, double y, double* phi, double* curv )
-
Evaluate the heading angle
phi
and the curvaturecrv
at a givenx
/y
-position for contact pointcpId
.
6.7.3. Corresponding MATLAB functions
[pz, data] = crg_eval_uv2z(data, puv)
-
Evaluate the
z
-values at the givenu
/v
-positions for data setdata
. [pz, data] = crg_eval_xy2z(data, pxy)
-
Evaluate the
z
-values at the givenx
/y
-positions for data setdata
. [pxy, data] = crg_eval_uv2xy(data, puv)
-
Evaluate the
x
/y
-positions of the givenu
/v
-positions for data setdata
. [puv, data] = crg_eval_xy2uv(data, pxy)
-
Evaluate the
u
/v
-positions of the givenx
/y
-positions for data setdata
. [iu, iv] = crg_eval_uv2iuiv(data, u, v)
-
Evaluate the index positions
iu
,iv
of the givenu
/v
-positions for data setdata
. [phi, data] = crg_eval_u2phi(data, pu)
-
Evaluate the heading angles
phi
at givenu
-positions for data setdata
. [crv, data] = crg_eval_u2crv(data, pu)
-
Evaluate the curvature values
crv
at givenu
-positions for data setdata
. [pxyz, data] = crg_eval_enh2xyz(data, penh)
-
Evaluate the local
x
/y
/'z'-positions of the given global positionspenh
(easting, northing, height) for data setdata
. [pxyz, data] = crg_eval_llh2xyz(data, pllh)
-
Evaluate the local
x
/y
/'z'-positions of the given geographic coordinatespllh
(latitude, longitude, height) for data setdata
.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 localx
/y
/'z'-positions-positions for data setdata
. [pllh, data] = crg_eval_xyz2llh(data, pxyz)
-
Evaluate the geographic coordinates
pllh
(latitude, longitude, height) of the given localx
/y
/'z'-positions for data setdata
.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.7.5. Related Topics
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 setdata1
and return the resulting data setdata
. 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 asroff2
. The last latitudinal cut ofdata
and the first latitudinal cut ofdata2
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
andiv
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 lenghtswlen
andbwlen
, 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 indata
. Merge existing banking into the road data. [data] = crg_s2z(data, rz)
-
Apply new slope defined by
rz
to the OpenCRG data indata
. 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
andiv
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 optionalwopt
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 inmmlim
.iu
andiv
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 ofdata
.iu
andiv
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 ofdata
.iu
andiv
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
asdata
with new u/v-incrementinc
and v-spacingv
.
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.8.5. Related topics
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
andv
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 polynomialppxy
in pp-form.uinc
specifies the reference line increment. The optional structopts
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 pointspxy
. The optionalopts
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-profilev
.
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.9.5. Related topics
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
andiv
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 indata
. [data] = crg_show_refline_elevation(data, iu)
-
Visualize the z-values in
data
along the reference line defined indata
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
andiv
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
andiv
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
andiv
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 vectorsu
andv
. [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 ofcrg_isequal()
.out
can be set tohtml
to publish the result as HTML. [data] = crg_show_peaks(data, pindex, su, sv, iu, iv)
-
Visualize peaks at
pindex
indata
.pindex
is usually the return value ofcrg_peakfinder()
.su
andsv
can be used to limit the visualization of peaks to a part of the grid.iu
andiv
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
andiv
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
andiv
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
andiv
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
andiv
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
andiv
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 indata
. 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
andiv
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
andiv
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 vectorsu
andv
. [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 vectorsu
andv
. [data] = crg_surf(data, x, y, z)
-
Create a three-dimensional surface plot of
z
overx
andy
using figure options defined indata
. [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.10.5. Related topics
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.
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 datadata
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 positionsllh
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 structell
and a map projection structpro
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 structell
and a map projection structpro
may be optionally provided. [llh ell pro] = map_pmap2geod_tm(enh, ell, pro)
-
Convert points
enh
from map coordinates to geodetic coordinatesllh
using backward transverse Mercator projection. An ellipsoid structell
and a map projection structpro
may be optionally provided. [xyz ell] = map_geod2ecef(llh, ell)
-
Convert points
llh
from a geodetic system to ECEF system. An ellipsoid structell
may be optionally provided. [xyzb tran] = map_ecef2ecef(xyza, tran, fwbw)
-
Transforms points
xyza
from one ECEF datum to another. A transformation structtran
specifying the transformation may be optionally provided. The optionalfwbw
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 coordinatesenh
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 coordinatesllh
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 northingsnorth
. Utility function needed for transverse Mercator projections. [marc ell pro] = map_ptm_phi2marc(phi, ell, pro)
-
Compute the meridional arc
marc
for given latitudesphi
. Utility function needed for transverse Mercator projections. [dat] = map_check(dat)
-
Check and update
dat
as used inmap_global2plocal
andmap_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 coordinateswgs
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 coordinateswgs
using the provided OpenCRG datadata
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
anddmin
define requirements for numerical consistency. [dist dbeg dend] = crg_wgs84_dist(wgs1, wgs2)
-
Evaluate the distances
dist
and bearingsdbeg
anddend
between the WGS 84 positions inwgs1
andwgs2
.dbeg
is the bearing as seen fromwgs1
.dend
is the bearing as seen fromwgs2
. [wgs2 dend] = crg_wgs84_invdist(wgs1, dbeg, dist)
-
Calculate WGS 84 positions
wgs2
defined by a WGS 84 base positionwgs1
, a bearingdbeg
, and a distancedist
.dend
is the bearing as seen fromwgs2
. [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.11.5. Related topics
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 returnstrue
if the data was checked successfully. Check reference line curvature indataSetId
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 indata
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.12.5. Related Topics
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.
6.13.2. Related C functions
The C-API does not provide functions for writing OpenCRG data.
6.13.3. Related MATLAB functions
[ier] = crg_write(data, file, type)
-
Write the OpenCRG data in
data
to the OpenCRG filefile
. By default, the file uses the KRBI format. The optional argumenttype
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');