7 Setting up the OpenCRG tools

7.1 Downloading the software package

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

  • Sample OpenCRG files.

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

  • MATLAB tools, including test scripts and samples.

  • OpenCRG documentation.

Steps

  1. Open www.asam.net/standards/detail/opencrg/.

  2. Navigate to the Download area.

  3. Follow the instructions to download the software package.

  4. Download the ZIP archive.

  5. Unpack the archive into a local directory.

What to do next

  • Compile the C source code.

  • Initialize the MATLAB tools.

Related topics

7.2 Setting up the C-API

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

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

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

7.2.4 Compiling the C-API using Makefiles

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

7.2.4.1 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/.

7.2.4.2 Steps

  1. Open a command line interpreter.

  2. Change to the c-api directory.

  3. Run make.

7.2.4.3 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/.

7.2.4.4 What to do next

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

7.2.4.5 Related topics

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

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

7.2.5.2 Steps

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

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

  3. Save your changes to the script.

  4. Execute the script.

7.2.5.3 Result

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

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

7.2.5.4 What to do next

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

7.2.5.5 Related topics

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

7.2.6.1 Prerequisites

  • You downloaded and unpacked the OpenCRG software package.

  • A C-compiler is installed on your computer.

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

7.2.6.3 What to do next

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

7.2.6.4 Related topics

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

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

7.2.7.2 Steps

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

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

7.2.7.3 Results

  • The C-API is set up successfully.

  • Images illustrating the various options and modifiers are created.

7.2.7.4 Related topics

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

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

7.2.9.1 Prerequisites

You have compiled the C-API.

7.2.9.2 Steps

  1. Open a command line interpreter.

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

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

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

7.2.9.3 Related topics

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

7.3 Setting up the MATLAB tools

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

7.3.2 Library files of the MATLAB tools

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

Table 11. Evaluation tools
Filename Description

crg_eval_enh2xyz.m

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

crg_eval_llh2xyz.m

Transform points in llh to x/y/z.

crg_eval_u2crv.m

Evaluate curvature at reference line positions.

crg_eval_u2phi.m

Evaluate heading angles at reference line positions.

crg_eval_uv2iuiv.m

Evaluate index positions of grid positions.

crg_eval_uv2xy.m

Evaluate local coordinates of grid positions.

crg_eval_uv2z.m

Evaluate z at grid position.

crg_eval_xy2uv.m

Transform points in x/y to u/v.

crg_eval_xy2z.m

Evaluate z at x/y-position.

crg_eval_xyz2enh.m

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

crg_eval_xyz2llh.m

Transform point in x/y/z to l/l/h.
Table 12. Visualization and analysis tools
Filename Description

copy_ax2fig.m

Copy current axes object to new figure.

crg_figure.m

Set up OpenCRG figure.

crg_isequal.m

Compare two OpenCRG data sets.

crg_peakfinder.m

Detect peaks in a OpenCRG data.

crg_plot_elgrid_cross_sect.m

Plot z-values over latitudinal cuts.

crg_plot_elgrid_limits.m

Plot the outer grid limits.

crg_plot_elgrid_long_sect.m

Plot z-values over longitudinal cuts.

crg_plot_elgrid_uvz_map.m

Plot z-values as uncurved orthographic image.

crg_plot_elgrid_xyz_map.m

Plot z-values as curved three-dimensional image.

crg_plot_refline_curvature.m

Plot curvature along the reference line.

crg_plot_refline_elevation.m

Plot the z-values along the reference line.

crg_plot_refline_heading.m

Plot heading angle along the reference line.

crg_plot_refline_slope_bank.m

Plot slope and banking along the reference line.

crg_plot_refline_xyz_map.m

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

crg_plot_refline_xy_map_and_curv.m

Plot reference line including curvature.

crg_plot_refline_xy_overview_map.m

Plot reference line in x/y-coordinates.

crg_plot_refpnt_distances.m

Plot distance of reference points to reference line.

crg_plot_road_uv2uvz_map.m

Plot road surface over a given uncurved grid.

crg_plot_road_uv2xyz_map.m

Plot road surface over a given curved grid.

crg_plot_road_uvz_map.m

Plot road surface as uncurved orthographic image.

crg_plot_road_xyz_map.m

Plot road surface as curved three-dimensional image.

crg_show.m

Visualize CRG data.

crg_show_elgrid_cuts_and_limits.m

Visualize the cuts and limits of the CRG

crg_show_elgrid_surface.m

Visualize z-values.

crg_show_info.m

Display information about the CRG.

crg_show_isequal.m

Visualize the result of comparing two OpenCRG files.

crg_show_peaks.m

Visualize peaks.

crg_show_refline_elevation.m

Visualize elevation along the reference line.

crg_show_refline_map.m

Visualize the reference line.

crg_show_refpnts_and_refline.m

Visualize reference points and reference line.

crg_show_road_surface.m

Visualize the road surface.

crg_show_road_uv2surface.m

Visualize the road surface on a given grid.

crg_surf.m

Plot a three-dimensional surface.
Table 13. File input and output tools
Filename Description

crg_read.m

Read OpenCRG file.

crg_single.m

Convert OpenCRG road data to type single.

crg_wrap.m

Wrap heading angles to +/- pi range.

crg_write.m

Write OpenCRG file.

ipl_demo.m

IPLOS write/read demonstration.

ipl_read.m

Read IPLOS file.

ipl_write.m

Write IPLOS file.

sdf_add.m

Add block to struct data file.

sdf_cut.m

Cut block from struct data file.

str_num2strn.m

Convert number to string of given length.
Table 14. Checking tools
Filename Description

crg_check.m

Run all OpenCRG data checks.

crg_check_curvature.m

Check OpenCRG curvature data.

crg_check_data.m

Check, fix, and complement OpenCRG data.

crg_check_head.m

Check OpenCRG road parameters data.

crg_check_mods.m

Check modifier data.

crg_check_mpro.m

Check OpenCRG map projection data.

crg_check_opts.m

Check OpenCRG options data.

crg_check_single.m

Check core OpenCRG data for type single.

crg_check_wgs84.m

Check OpenCRG WGS 84 data.
Table 15. Modification tools
Filename Description

crg_append.m

Append a second compatible OpenCRG to a first OpenCRG.

crg_b2z.m

Apply banking to OpenCRG data.

crg_cut_iuiv.m

Cut out a part of a OpenCRG road.

crg_ext_banking.m

Extract banking from OpenCRG data.

crg_ext_slope.m

Extract slope from OpenCRG data.

crg_filter.m

Apply filter to OpenCRG data.

crg_flip.m

Flip OpenCRG data.

crg_limiter.m

Limits z-values in OpenCRG data.

crg_map_uv2uv.m

Map z-values from one grid to another.

crg_map_xy2xy.m

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

crg_mods.m

Apply modifiers to data.

crg_rerender.m

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

crg_s2z.m

Apply slope to OpenCRG data.

crg_separate_sb.m

Separate slope and banking.

smooth_firfilt.m

Smooth input signals with symmetric FIR filter.
Table 16. Generation tools
Filename Description

crg_check_uv_descript.m

Check uv_descript and create a v-profile.

crg_gen_csb2crg0.m

Generate synthetic OpenCRG data.

crg_gen_ppxy2phi.m

Generate reference line heading from polynomial.

crg_gen_pxy2ppxy.m

Generates smooth polynomial from reference points.

crg_perform2surface.m

Generate synthetical surface.
Table 17. Geographic referencing tools
Filename Description

crg_wgs84_crg2html.m

Generate HTML file to visualize OpenCRG data in a map.

crg_wgs84_dist.m

Evaluate distance and bearing between WGS 84 positions.

crg_wgs84_invdist.m

Calculate WGS 84 positions by distance and bearing.

crg_wgs84_setend.m

Set WGS 84 end coordinate.

crg_wgs84_wgs2url.m

Generate URL to show WGS 84 information on Google Maps

crg_wgs84_wgsxy2wgs.m

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

crg_wgs84_xy2wgs.m

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

map_check.m

Check and update DAT struct.

map_check_elli.m

Check and update ellipsoid struct.

map_check_proj.m

Check and update map projection struct.

map_check_tran.m

Check and update datum transformation struct.

map_ecef2ecef.m

Datum transformation in ECEF system.

map_ecef2geod.m

Convert points from ECEF system to geodetic system.

map_geod2ecef.m

Convert points from geodetic system to ECEF system.

map_geod2pmap.m

Forward map projection.

map_geod2pmap_tm.m

Forward transverse Mercator projection.

map_global2plocal.m

Forward projection: global to projected local.

map_intro.m

MAP routines introduction

map_plocal2global.m

Backward projection: projected local to global.

map_pmap2geod_tm.m

Backward projection: transverse Mercator.

map_ptm_north2initiallat.m

Transverse Mercator utility function.

map_ptm_phi2marc.m

Transverse Mercator utility function: meridional arc.

map_wgs2html.m

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

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

7.3.3.1 Prerequisites

You have downloaded and unpacked the OpenCRG software package.

7.3.3.2 Steps

  1. In MATLAB, switch to the Command Window.

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

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

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

7.3.3.3 Result

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

7.3.3.4 What to do next

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

7.3.3.5 Related topics

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

7.3.4.1 Prerequisites

You have initialized the MATLAB tools.

7.3.4.2 Steps

  1. In MATLAB, switch to the Command Window.

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

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

7.3.4.3 Result

The help text is displayed in the Command Window.

7.3.4.4 Related topics

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

7.3.5.1 Prerequisites

  • You have initialized the MATLAB tools.

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

7.3.5.2 Steps

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

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

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

7.3.5.3 Related topics

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

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