8 Using the OpenCRG tools

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

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

8.3 Reading OpenCRG files

Reading an OpenCRG file loads its content into memory.

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

8.3.2 Related MATLAB functions

[data] = crg_read(file)

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

8.3.3 Examples

8.3.3.1 C examples

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

8.3.3.2 MATLAB examples

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

8.3.4 Related topics

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

8.4.1 Prerequisites

You have loaded an OpenCRG data set.

8.4.2 Corresponding C functions

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

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

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

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

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

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

extern void crgDataSetModifiersPrint( int dataSetId )

Print the current modifier settings of the data set dataSetId.

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

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

int crgDataSetModifierRemove( int dataSetId, unsigned int modId )

Remove the modifier modID from the data set dataSetId.

int crgDataSetModifierRemoveAll( int dataSetId )

Remove all modifiers from the data set dataSetId.

void crgDataSetModifierSetDefault( int dataSetId )

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

void crgDataSetModifiersApply( int dataSetId )

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

8.4.3 Corresponding MATLAB functions

[data] = crg_mods(data)

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

8.4.4 Examples

8.4.4.1 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 );

8.4.4.2 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);

8.4.5 Related topics

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

8.5.1 Prerequisites

  • You have loaded an OpenCRG data set.

  • You have set and applied modifiers.

8.5.2 Corresponding C functions

int cpId = crgContactPointCreate( int dataSetId )

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

int crgContactPointDelete( int cpId )

Delete the contact point with the ID cpId.

int crgContactPointDeleteAll( int dataSetId )

Delete all contact points associated with the data set dataSetId.

8.5.3 Corresponding MATLAB functions

The MATLAB tools do not use contact points.

8.5.4 Examples

8.5.4.1 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 );

8.5.5 Related Topics

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

8.6.1 Prerequisites

  • You have loaded an OpenCRG data set.

  • You have set and applied modifiers.

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

8.6.2 Corresponding C functions

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

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

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

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

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

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

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

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

void crgContactPointOptionsPrint( int cpId )

Print the current option settings of the contact point cpId.

int crgContactPointOptionRemove( int cpId, unsigned int optionId )

Remove the option optionID from the contact point cpId.

int crgContactPointOptionRemoveAll( int cpId )

Remove all options from the contact point cpId.

void crgContactPointSetDefaultOptions( int cpId )

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

8.6.3 Corresponding MATLAB functions

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

8.6.4 Examples

8.6.4.1 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 );

8.6.4.2 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);

8.6.5 Related topics

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

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

8.7.2 Corresponding C functions

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

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

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

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

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

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

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

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

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

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

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

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

8.7.3 Corresponding MATLAB functions

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

8.7.4 Examples

8.7.4.1 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 );

8.7.4.2 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]);

8.7.5 Related Topics

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

8.8.1 Prerequisites

  • You have loaded an OpenCRG data set.

8.8.2 Corresponding C functions

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

8.8.3 Corresponding MATLAB functions

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

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

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

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

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

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

[data] = crg_b2z(data, b)

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

[data] = crg_s2z(data, rz)

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

[data] = crg_ext_slope(data, p)

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

[data] = crg_ext_banking(data, pp)

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

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

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

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

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

[data] = crg_wrap(data)

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

[data] = crg_flip(data)

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

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

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

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

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

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

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

8.8.4 Examples

8.8.4.1 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);

8.8.5 Related topics

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

8.9.1 Prerequisites

None.

8.9.2 Corresponding C functions

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

8.9.3 Corresponding MATLAB functions

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

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

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

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

[ppxy] = crg_gen_pxy2ppxy(pxy, opts)

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

[v] = crg_check_uv_descript(uv_descript, posmode)

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

8.9.4 Examples

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

8.9.5 Related topics

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

8.10.1 Prerequisites

  • You have loaded an OpenCRG data set.

  • You have set and applied modifiers.

  • You have set options.

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

8.10.3 Corresponding MATLAB functions

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

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

[data] = crg_show_refline_map(data, iu)

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

[data] = crg_show_refpnts_and_refline(data, pxy)

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

[data] = crg_show_refline_elevation(data, iu)

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

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

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

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

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

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

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

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

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

[data] = crg_show_info(data)

Display information about data in a text box.

[ ] = crg_show_isequal(dd, out)

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

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

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

[data] = crg_plot_refline_xy_overview_map(data, iu)

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

[data] = crg_plot_refline_curvature(data, iu)

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

[data] = crg_plot_refline_elevation(data, iu)

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

[data] = crg_plot_refline_heading(data, iu)

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

[data] = crg_plot_refline_slope_bank(data, iu)

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

[data] = crg_plot_refline_xyz_map(data, iu)

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

[data] = crg_plot_refline_xy_map_and_curv(data, iu)

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

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

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

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

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

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

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

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

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

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

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

[data] = crg_plot_refpnt_distances(data, pxy)

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

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

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

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

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

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

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

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

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

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

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

[data] = crg_figure(data)

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

[ ] = copy_ax2fig()

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

8.10.4 Examples

8.10.4.1 MATLAB examples

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

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

8.10.5 Related topics

8.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. Figure 5 shows the available coordinate systems and transformations. Many of these functions are generic and may also be used for data not in OpenCRG format.

geo transformations
Figure 5. Overview of coordinate transformations

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

8.11.1 Prerequisites

  • You have loaded an OpenCRG data set.

  • The OpenCRG data contains the required map projection data.

8.11.2 Corresponding C functions

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

8.11.3 Corresponding MATLAB functions

map_intro[]

Display introductory information on handling geographic data.

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

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

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

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

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

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

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

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

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

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

[xyz ell] = map_geod2ecef(llh, ell)

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

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

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

[llh ell] = map_ecef2geod(xyz, ell)

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

[enh dat] = map_global2plocal(llh, dat)

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

[llh dat] = map_plocal2global(enh, dat)

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

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

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

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

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

[dat] = map_check(dat)

Check and update dat as used in map_global2plocal and map_plocal2global.

[ell] = map_check_elli(ell)

Check and update ellipsoid struct ell.

[pro] = map_check_proj(pro)

Check and update map projection struct pro.

[tran] = map_check_tran(tran)

Check and update datum transformation struct tran.

[url] = crg_wgs84_wgs2url(wgs, opts)

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

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

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

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

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

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

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

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

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

[data] = crg_wgs84_setend(data, dref)

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

8.11.4 Examples

8.11.4.1 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)

8.11.5 Related topics

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

8.12.1 Prerequisites

  • You have loaded an OpenCRG data set.

8.12.2 Corresponding C functions

int crgCheck( int dataSetId )

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

8.12.3 Corresponding MATLAB functions

[data] = crg_check(data)

Run all available checks on the OpenCRG data in data.

[data] = crg_check_opts(data)

Check OpenCRG options in data for consistent definitions and values.

[data] = crg_check_mods(data)

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

[data] = crg_check_head(data)

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

[data] = crg_check_mpro(data)

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

[data] = crg_check_data(data)

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

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

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

[data] = crg_check_single(data)

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

[data] = crg_check_wgs84(data)

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

8.12.4 Examples

8.12.4.1 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;
}

8.12.4.2 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);

8.12.5 Related Topics

  • <<Reading OpenCRG files>

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

8.13.1 Prerequisites

  • You have loaded or generated an OpenCRG data set.

8.13.2 Related C functions

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

8.13.3 Related MATLAB functions

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

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

[data] = crg_single(data)

Convert road data in data to type single.

8.13.4 Examples

8.13.4.1 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');

8.13.5 Related topics