EC2007 ECDIS KERNEL

Version 5.20

Programming Guide

May 2015

SevenCs GmbH, Hamburg, Germany

EC2007 ECDIS Kernel Programming Guide

SevenCs GmbH
Atlantic Haus
Zirkusweg1
D-20359 Hamburg
Tel. +49 (0)40/851 72 40
FAX +49 (0)40/851 72 4-79
[Link]

Copyright:
All rights reserved. No part of this document may be reproduced, in any form or by any
means, disclosed or used by any person who has not received prior written authorization
from SevenCs GmbH.
Brand names:
Brand names, logos and trademarks used in this document remain the property of their
respective owners.
Referrals and links:
SevenCs does not assume any liability for any external content linked to our site / to this
document, including links provided in our website. SevenCs has no influence on the content
of such sites. The owners of such linked websites take sole responsibility for their content.
Disclaimer:
SevenCs does not guarantee any actuality, correctness, completeness or quality of the
information provided. Claims of liability referring to material or ideal damages, due to the
use or non-use of the information or due to the use of wrong and incomplete information,
are strictly ruled out, as long as there is no verifiable wilful or reckless fault on the part of
SevenCs GmbH.
2
 EC2007 ECDIS Kernel Programming Guide

Preface
This document is aimed at programmers who are developing a chart display system using
the EC2007 ECDIS Kernel SDK. It gives a step by step introduction to the structure and
functionality of the EC2007 ECDIS Kernel SDK as well as a complete description of all its
components.
For instructions on installation and registration of the EC2007 ECDIS Kernel see the
EC2007_InstallationGuide.
For general background information about the different chart products, their formats and
related standards see the document EC2007_BackgroundInformation.

3
EC2007 ECDIS Kernel Programming Guide

Contents
Preface ..........................................................................................................3

Contents .........................................................................................................4

1 Introduction..................................................................................... 14
1.1 Document Conventions ........................................................................................... 14
1.2 Trademarks .............................................................................................................. 15

2 Background Information .................................................................. 16

3 Supported Data Formats .................................................................. 17

4 Getting Started ................................................................................ 18

4.1 Introduction ............................................................................................................. 18
4.2 Getting Help ............................................................................................................. 18
4.3 Compiler Settings ..................................................................................................... 18
4.3.1 Windows - Visual Studio 2005/2010/2013: .........................................................................19
4.3.2 Linux / gcc .............................................................................................................................19
4.4 Multi-threading........................................................................................................ 19
4.5 Example Programs and Data.................................................................................... 19

5 Function Sets ................................................................................... 20

5.1 EC27_Admin............................................................................................................. 21
5.2 EC27_AIS .................................................................................................................. 21
5.3 EC27_ARINC ............................................................................................................. 21
5.4 EC27_ARCS ............................................................................................................... 21
5.5 EC27_BSB ................................................................................................................. 22
5.6 EC27_DENC .............................................................................................................. 22
5.7 EC27_DNC ................................................................................................................ 22
5.8 EC27_Draw............................................................................................................... 23
5.9 EC27_Easy ................................................................................................................ 23
5.10 EC27_Globe.............................................................................................................. 23
5.11 EC27_Monitor .......................................................................................................... 24
5.12 EC27_Navigation ...................................................................................................... 24
5.13 EC27_Print ............................................................................................................... 24
5.14 EC27_River ............................................................................................................... 25

4
 EC2007 ECDIS Kernel Programming Guide

5.15 EC27_Route.............................................................................................................. 25
5.16 EC27_S57 ................................................................................................................. 26
5.17 EC27_SENC ............................................................................................................... 26
5.18 EC27_Sensor ............................................................................................................ 27
5.19 EC27_Symbol ........................................................................................................... 27
5.20 EC27_Tides ............................................................................................................... 28
5.21 EC27_Vector ............................................................................................................ 28

6 Core Functionality............................................................................ 29
6.1 Definition of the Environment ................................................................................. 29
6.2 Registration .............................................................................................................. 29
6.3 Module Handling ..................................................................................................... 31
6.4 Dictionary Handling ................................................................................................. 32
6.5 Chart Installation ..................................................................................................... 34
6.5.1 Chart Provision .....................................................................................................................34
6.5.2 DENC Structure .....................................................................................................................34
[Link] Creation of DENC Structure ..................................................................................... 34
[Link] DENC Directories and Files ...................................................................................... 35
[Link] DENC Structure Handling ......................................................................................... 36
[Link] DENC Callback Function ........................................................................................... 36
[Link] Installation Passport ................................................................................................ 37
[Link] Producer Agency Catalogue..................................................................................... 38
6.5.3 SENC Catalogue ....................................................................................................................38
6.5.4 General Chart Import ...........................................................................................................38
6.5.5 directENC Packages ..............................................................................................................39
6.5.6 SENC Files .............................................................................................................................40
6.5.7 S-57 Files...............................................................................................................................40
6.5.8 S-57 Exchange Sets ...............................................................................................................40
6.5.9 S-63 Exchange Sets ...............................................................................................................41
[Link] EC2007 S-63 Interface.............................................................................................. 41
[Link] S-63 User Permit ...................................................................................................... 42
[Link] Scheme Administrator (SA) Certificates .................................................................. 42
[Link] Cell Permit Handling ................................................................................................ 42
[Link] Detection of Encrypted Data ................................................................................... 43
[Link] Reading S-63 cells .................................................................................................... 43
[Link] S-63 Error Messages ................................................................................................ 44
[Link] S-63 Meta Information ............................................................................................ 47
[Link] High level S-63 Handling .......................................................................................... 47
6.5.10 Applying S-57 Updates .........................................................................................................47
6.5.11 Retrieving Update Information ............................................................................................48
6.5.12 Deleting Charts .....................................................................................................................49
[Link] directENC Packages.................................................................................................. 49
[Link] Single Charts ............................................................................................................ 50
6.5.13 ACES ......................................................................................................................................50
6.5.14 ARCS / BSB ............................................................................................................................50

5
EC2007 ECDIS Kernel Programming Guide

6.5.15 Other Files ............................................................................................................................51

6.6 Chart Display ............................................................................................................ 51
6.6.1 View Structure ......................................................................................................................54
6.6.2 View Handling.......................................................................................................................54
6.6.3 The Viewport ........................................................................................................................56
6.6.4 Chart Loading .......................................................................................................................56
[Link] General Description ................................................................................................. 56
[Link] Chart Loading Function ............................................................................................ 59
[Link] Cell List and Cache ................................................................................................... 59
[Link] Cell Order ................................................................................................................. 60
6.6.5 Chart Symbolization .............................................................................................................60
[Link] Chart Display Settings .............................................................................................. 61
[Link] Display List ............................................................................................................... 61
[Link] Display List Generator.............................................................................................. 61
[Link] Symbolization Function ........................................................................................... 63
6.6.6 Chart Projection ...................................................................................................................63
[Link] Chart Datum............................................................................................................. 64
[Link] Projection Types ...................................................................................................... 65
[Link] Projection Definition ................................................................................................ 66
[Link] Projection Buffer ...................................................................................................... 69
6.6.7 Chart Drawing.......................................................................................................................69
[Link] Color Handling ......................................................................................................... 70
[Link] View Draw Initialization ........................................................................................... 71
[Link] Drawing Settings ...................................................................................................... 72
[Link] Drawing Function ..................................................................................................... 72
[Link] Tiling......................................................................................................................... 73
6.6.8 Callbacks ...............................................................................................................................73

7 Specific ECDIS Functionality ............................................................. 75

7.1 Chart Display and Mariner’s Settings ...................................................................... 75
7.1.1 Display Categories ................................................................................................................75
7.1.2 Display Selectors...................................................................................................................75
7.1.3 Chart Settings .......................................................................................................................76
[Link] Lights ........................................................................................................................ 77
[Link] Soundings................................................................................................................. 77
[Link] Depth Contours and Areas Display .......................................................................... 77
[Link] Overscale Indication ................................................................................................ 79
7.1.4 Viewing Groups ....................................................................................................................79
7.1.5 Date Dependent Objects ......................................................................................................81
7.1.6 Other Mariner’s Settings ......................................................................................................81
[Link] Past Track ................................................................................................................. 81
[Link] Alternate Route ....................................................................................................... 82
[Link] Cross Track Limits .................................................................................................... 82
[Link] Symbol Fail ............................................................................................................... 82
7.1.7 Other Chart Display Settings ................................................................................................82
[Link] Depth Adjustments .................................................................................................. 82
[Link] Display Priority ......................................................................................................... 83
[Link] Highlighting Objects ................................................................................................. 83
[Link] Better Usage Indicator ............................................................................................. 84

6
 EC2007 ECDIS Kernel Programming Guide

[Link] Filtering Objects ....................................................................................................... 84

7.1.8 Additional Mariner’s Information ........................................................................................85
7.1.9 Chart Drawing Settings .........................................................................................................85
[Link] Set Symbol Filter ...................................................................................................... 85
[Link] Text Settings ............................................................................................................ 85
[Link] Scale Filter Warning ................................................................................................. 85
7.1.10 Default Values for Chart Settings .........................................................................................86
7.2 Chart Overlays.......................................................................................................... 87
7.2.1 Overlay Cells .........................................................................................................................87
[Link] File-based Overlay Cell............................................................................................. 87
[Link] Overlay Cell in RAM ................................................................................................. 88
7.2.2 Symbolizing and Drawing Overlay Cells ...............................................................................89
7.3 Danger and Caution Highlight.................................................................................. 89
7.3.1 Definition of danger and caution objects .............................................................................89
7.3.2 Detection and notification of danger and caution objects ..................................................90
7.4 Indication of Automatic Updates............................................................................. 90
7.5 Route Handling ........................................................................................................ 90
7.5.1 Creating Routes ....................................................................................................................91
7.5.2 Deleting Routes ....................................................................................................................93
7.5.3 Changing Routes ...................................................................................................................94
7.5.4 Selecting Routes ...................................................................................................................95
7.5.5 Checking Routes ...................................................................................................................96
7.5.6 Clearing Routes...................................................................................................................101
7.5.7 Exchanging Routes..............................................................................................................102
7.5.8 Route Database ..................................................................................................................103
[Link] Database Initialization ........................................................................................... 103
[Link] Database Queries................................................................................................... 103
[Link] Database Modification .......................................................................................... 105
[Link] Database Calculation ............................................................................................. 108
7.6 Monitoring ............................................................................................................. 109
7.6.1 Activating a Waypoint ........................................................................................................110
7.6.2 Cross Track Distance...........................................................................................................110
7.6.3 Anti-Grounding ...................................................................................................................111
[Link] The Guard Zone ..................................................................................................... 111
[Link] Display of Guard Zone............................................................................................ 114
7.6.4 Past Track ...........................................................................................................................115
7.6.5 Prediction ...........................................................................................................................116
7.7 Manual Updating ................................................................................................... 117
7.7.1 The Manual Update Cell .....................................................................................................117
7.7.2 The Manual Update List .....................................................................................................118
[Link] Adding Objects to List ............................................................................................ 120
7.7.3 Creating Objects .................................................................................................................121
7.7.4 Deleting Objects .................................................................................................................122
7.7.5 Moving Objects...................................................................................................................122
7.7.6 Creating Annotations .........................................................................................................122
7.7.7 Modifying Objects ..............................................................................................................123
7.7.8 Withdrawing Manual Updates ...........................................................................................123
7.7.9 Querying Manual Updates .................................................................................................123

7
EC2007 ECDIS Kernel Programming Guide

7.7.10 Displaying Manual Updates................................................................................................124

7.8 Navigational Calculations....................................................................................... 124
7.9 Sensor Data ............................................................................................................ 124
7.9.1 Introduction........................................................................................................................124
7.9.2 NMEA Data Reading ...........................................................................................................125
7.9.3 NMEA Data Registering ......................................................................................................127
7.9.4 NMEA Data Recording ........................................................................................................130
7.10 Radar ...................................................................................................................... 131
7.10.1 Radar Overlay .....................................................................................................................131
7.10.2 Display of radar (ARPA) targets ..........................................................................................131
7.11 AIS .......................................................................................................................... 131
7.11.1 The AIS Interface Library ....................................................................................................132
7.11.2 Transponder Connection ....................................................................................................134
7.11.3 AIS Callback ........................................................................................................................135
7.11.4 AIS Target Information .......................................................................................................135
[Link] Enumerated Types and Type Definitions............................................................... 137
[Link] Structured Types .................................................................................................... 139
7.11.5 Display of AIS Targets .........................................................................................................141
7.12 Chart 1.................................................................................................................... 143

8 ARCS .............................................................................................. 145

8.1 License Conditions ................................................................................................. 146
8.1.1 Manufacture and Promotion..............................................................................................147
8.1.2 Sub Licensing ......................................................................................................................147
8.1.3 Marking of ECDIS ................................................................................................................147
8.2 Registration ............................................................................................................ 148
8.3 ARCS Directory and File Structure ......................................................................... 148
8.4 ARCS Authorization ................................................................................................ 150
8.5 ARCS Installation .................................................................................................... 150
8.5.1 The ARCS Chart Catalogue..................................................................................................150
8.5.2 Reading ARCS Chart Permits ..............................................................................................151
8.5.3 Reading the ARCS Chart Catalogue ....................................................................................152
8.5.4 Installing Charts and Updates.............................................................................................152
[Link] Installing Charts ..................................................................................................... 152
[Link] Installing Updates .................................................................................................. 153
[Link] Updating local ARCS Chart Database ..................................................................... 153
8.6 ARCS Display .......................................................................................................... 153
8.6.1 Manual Selection ................................................................................................................153
8.6.2 Semi-Automatic Selection ..................................................................................................154
8.6.3 Checking for the Chart Permit ............................................................................................155
8.6.4 Loading an ARCS Chart .......................................................................................................155
8.6.5 Setting ARCS Colors ............................................................................................................156
[Link] ARCS Plus Overlay .................................................................................................. 157
8.6.6 Drawing the Chart or Plan ..................................................................................................158
8.6.7 Indicating and Viewing ARCS Updates ...............................................................................159
8.7 Releasing Resources .............................................................................................. 160
8
 EC2007 ECDIS Kernel Programming Guide

8.8 Additional Chart Permit Handling.......................................................................... 161

8.9 ARCS Demonstration Mode ................................................................................... 163
8.10 Additional ARCS Functions..................................................................................... 163
8.10.1 Chart Information ...............................................................................................................164
8.10.2 Chart Notes.........................................................................................................................165
8.10.3 Coordinate Conversion Functions ......................................................................................165
8.11 ARCS Error Handling .............................................................................................. 166
8.11.1 Security Errors ....................................................................................................................166
8.11.2 Internal Kernel Error Messages ..........................................................................................170

9 Non-ENC Products.......................................................................... 172

9.1 Special Chart Display Technology .......................................................................... 173
9.1.1 Data Overlay .......................................................................................................................173
9.1.2 Data Displacement .............................................................................................................174
9.2 Admiralty Information Overlay .............................................................................. 174
9.3 InlandENC............................................................................................................... 175
9.3.1 Dictionary Handling ............................................................................................................175
9.3.2 IENC Installation .................................................................................................................175
9.3.3 IENC Display........................................................................................................................176
9.3.4 Display of IENC Notice Marks .............................................................................................176
9.4 Additional Military Layers (AML) ........................................................................... 177
9.4.1 Dictionary Handling ............................................................................................................178
9.4.2 AML Chart Installation ........................................................................................................178
9.4.3 AML Chart Loading and Display..........................................................................................179
9.5 DNC, VMap, TOD.................................................................................................... 180
9.5.1 Dictionary Handling ............................................................................................................181
9.5.2 VPF Import ..........................................................................................................................181
9.5.3 DNC Updating .....................................................................................................................182
9.5.4 VPF Chart Display ...............................................................................................................182
[Link] S-52 Symbolization ................................................................................................ 182
[Link] GeoSym Handling................................................................................................... 183
9.5.5 Navigational Functions .......................................................................................................184
9.6 ARINC ..................................................................................................................... 184
9.6.1 Dictionary Handling ............................................................................................................184
9.6.2 ARINC Display .....................................................................................................................185
9.7 MIL-2525 ................................................................................................................ 185
9.7.1 Installation ..........................................................................................................................186
9.7.2 Dictionary Handling ............................................................................................................186
9.7.3 Lookup Table Handling .......................................................................................................186
9.7.4 Creating a New MIL-2525 Data Set ....................................................................................187
9.7.5 Example Data......................................................................................................................187
9.7.6 Object Class and Attributes ................................................................................................188
9.8 bathymetric ENC (bENC) ........................................................................................ 190
9.9 User-Defined Chart Objects ................................................................................... 190
9.9.1 User-Defined Dictionaries ..................................................................................................190
[Link] Format.................................................................................................................... 190

9
EC2007 ECDIS Kernel Programming Guide

[Link] Implementation ..................................................................................................... 192

9.9.2 User-Defined Lookup Tables ..............................................................................................193
[Link] Format.................................................................................................................... 193
[Link] Implementation ..................................................................................................... 194
9.9.3 Symbols, Line Styles and Area Fills .....................................................................................194
9.10 Raster Charts.......................................................................................................... 194
9.10.1 BSB ......................................................................................................................................194
9.10.2 GeoTiff ................................................................................................................................197

10 Dictionary Access ........................................................................... 199

11 Data Access.................................................................................... 204

11.1 Cell File Access ....................................................................................................... 204
11.2 Cell Header Access ................................................................................................. 205
11.2.1 Cell Name ...........................................................................................................................206
11.2.2 Cell Product ........................................................................................................................207
11.3 Cell Data Access ..................................................................................................... 207
11.3.1 Retrieving Cells ...................................................................................................................207
11.3.2 Retrieving Feature Objects .................................................................................................208
11.3.3 Retrieving Primitives, Nodes, and Edges ............................................................................208
11.3.4 Accessing Feature Objects..................................................................................................209
[Link] Class Token ............................................................................................................ 209
[Link] Group ..................................................................................................................... 210
[Link] Identifiers ............................................................................................................... 210
[Link] Status ..................................................................................................................... 210
[Link] Attributes ............................................................................................................... 210
[Link] Relation to Feature Objects ................................................................................... 213
[Link] Retrieving Feature Objects Related to a Given Feature Object ............................ 213
[Link] Retrieving Feature Objects Related to a Given Feature Object One by One ........ 213
[Link] Relation to Primitives............................................................................................. 214
[Link] Retrieving all Primitives of a Given Feature Object ............................................... 214
[Link] Retrieving Primitives of a Given Feature Object One by One ............................... 214
11.3.5 Accessing Primitives ...........................................................................................................216
[Link] Identifier and Status .............................................................................................. 217
[Link] Type........................................................................................................................ 217
[Link] Relation to Feature Objects ................................................................................... 217
[Link] Retrieving All Feature Objects Linked to a Primitive ............................................. 217
[Link] Retrieving Feature Objects Linked to a Primitive One by One .............................. 218
[Link] List of Segments ..................................................................................................... 218
[Link] Retrieving all Nodes or Edges Related to a Primitive ............................................ 218
[Link] Retrieving Nodes or Edges Related to a Primitive One by One ............................. 219
11.3.6 Accessing Nodes .................................................................................................................221
[Link] Identifier and Status .............................................................................................. 221
[Link] Type........................................................................................................................ 221
[Link] Position, Dimension, and Depth ............................................................................ 221
[Link] Attribute List .......................................................................................................... 222
[Link] Relation to Primitives............................................................................................. 224
11.3.7 Accessing Edges ..................................................................................................................225

10
 EC2007 ECDIS Kernel Programming Guide

[Link] Identifier and Status .............................................................................................. 225

[Link] Vertex List, Number of Vertices and Dimension ................................................... 225
[Link] Attribute List .......................................................................................................... 227
[Link] Relation to Primitives............................................................................................. 227
[Link] Relation to Bounding Node ................................................................................... 227
11.4 Creating a Cell ........................................................................................................ 228
11.4.1 Setting Cell Header Values .................................................................................................229
11.4.2 Deleting Cells ......................................................................................................................229
11.4.3 Deleting Cell Content..........................................................................................................229
11.4.4 Reorganizing the Cell, Reducing its Size .............................................................................229
11.4.5 Specifying the Storage Type ...............................................................................................230
11.4.6 Removing Orphaned Object Components .........................................................................230
11.4.7 Checking Cells for Errors in Data Structure ........................................................................231
11.5 Creating and Modifying Objects ............................................................................ 231
11.5.1 Creating Objects .................................................................................................................231
11.5.2 Deleting Objects .................................................................................................................234
11.5.3 Modifying Objects ..............................................................................................................237
[Link] Object Identifiers and Status ................................................................................. 238
[Link] Feature Objects...................................................................................................... 238
[Link] Nodes ..................................................................................................................... 239
[Link] Attributes ............................................................................................................... 239
[Link] Geographic Position ............................................................................................... 240
[Link] Relations ................................................................................................................ 242

12 Extended Functionality .................................................................. 244

12.1 Manual Chart Installation ...................................................................................... 244
[Link] Manual SENC Catalogue Handling ......................................................................... 244
[Link] Catalogue List......................................................................................................... 244
[Link] Reading SENC Catalogue Content.......................................................................... 244
12.2 Manual Chart Display............................................................................................. 244
12.2.1 Viewport Definition ............................................................................................................245
12.2.2 Chart Loading .....................................................................................................................245
[Link] Single Cell Loading ................................................................................................. 246
12.2.3 Chart Symbolization ...........................................................................................................247
12.2.4 Chart Drawing.....................................................................................................................248
12.3 Chart Pick Report ................................................................................................... 248
12.4 Referenced Files..................................................................................................... 249
12.5 User-Defined Viewports ........................................................................................ 251
12.6 User-Defined Projections....................................................................................... 251
12.7 Globe ...................................................................................................................... 254
12.7.1 Displaying the Globe and Harbors ......................................................................................254
12.7.2 Displaying the Globe and SENC Coverage ..........................................................................257
12.7.3 Displaying the Globe and Routes .......................................................................................257
12.7.4 Searching Nearest Harbor ..................................................................................................257
12.7.5 Other Globe Functions .......................................................................................................257
12.8 World Data Set ....................................................................................................... 258

11
EC2007 ECDIS Kernel Programming Guide

12.9 World Overview ..................................................................................................... 259

12.10 Localization ............................................................................................................ 260
12.10.1 Display of Chart Text ..........................................................................................................260
12.10.2 Display of Pick Report.........................................................................................................260
12.11 Dynamic Overlay Drawings .................................................................................... 261
12.12 Drawing Functions ................................................................................................. 262
12.12.1 Drawing Symbols ................................................................................................................262
12.12.2 Drawing Lines and Areas ....................................................................................................262
12.13 Display Functions ................................................................................................... 263
12.14 Tidal Predictions .................................................................................................... 263

13 Miscellaneous ................................................................................ 265

13.1 Rendering Performance ......................................................................................... 265
13.1.1 Multi-threading ..................................................................................................................265
13.1.2 Caching of lookup table entries..........................................................................................265
13.1.3 Processor Intensive Functions ............................................................................................266
[Link] Official Chart Boundary Calculation....................................................................... 266
[Link] Shallow Water Dangers ......................................................................................... 266
[Link] Overscale Pattern .................................................................................................. 266
[Link] Depth Contour Labels ............................................................................................ 266
13.2 Chart Display Clutter – SCAMIN ............................................................................. 266
13.3 Server/Client Applications ..................................................................................... 267
13.3.1 Chart Maintenance .............................................................................................................267
13.3.2 ENC Licensing......................................................................................................................268

14 Additional Tools............................................................................. 269

14.1 WMS Library .......................................................................................................... 269
14.1.1 Components .......................................................................................................................269
14.1.2 Server Functionality............................................................................................................270
[Link] Serving Layer Manager .......................................................................................... 270
[Link] URL Parser .............................................................................................................. 271
[Link] Workflow ............................................................................................................... 271
[Link] URL Callback Framework ....................................................................................... 272
[Link] XML Exception Generation .................................................................................... 272
[Link] XML Capabilities Generator ................................................................................... 273
14.1.3 Client Functionality.............................................................................................................273
[Link] URL Generator ....................................................................................................... 273
14.1.4 Common Functionality .......................................................................................................274
14.2 3D Library ............................................................................................................... 275

15 Release Notes ................................................................................ 276

15.1 Version 5.20.0 ........................................................................................................ 276
15.1.1 Standard Compliance .........................................................................................................276
[Link] Detection and indication of navigation related objects ........................................ 276
[Link] Viewing group layers and display selectors ........................................................... 276

12
 EC2007 ECDIS Kernel Programming Guide

[Link] Pick report.............................................................................................................. 276

[Link] Display of date dependent objects ........................................................................ 277
[Link] Indication of overlapping cells ............................................................................... 277
[Link] Indication of automated updates .......................................................................... 277
[Link] S-52 Ed.4 / EC2007 ECDIS Kernel cross-reference ................................................. 277
[Link] Test Frame – S-64 .................................................................................................. 278
15.1.2 Bug Fixes .............................................................................................................................278
15.1.3 Registration ........................................................................................................................279
15.1.4 Development Environment ................................................................................................279
[Link] New supported platforms...................................................................................... 279
[Link] Linking of Linux system libraries ............................................................................ 279
15.2 Version 5.18.2 ........................................................................................................ 280
15.3 Version 5.18.0 ........................................................................................................ 280

16 Annex ............................................................................................ 282

A. EcNmea Data Structures ........................................................................................ 282

13
EC2007 ECDIS Kernel Programming Guide

1 Introduction
1.1 Document Conventions
This manual uses several conventions to highlight certain words and phrases and draw
attention to specific pieces of information.

Font: used for:

Calibri plain text in this document.
Calibri bold program or tool names and for program settings.
Calibri bold italic file names or environment variables.
Calibri blue bold cross references or other documentation.
Calibri blue underline hyperlinks.
Calibri red bold command line calls or Kernel function calls.

Important notes are displayed in shaded text boxes.

Please note:
Such note box displays important information which should not be ignored.

Simple file content is displayed in black.

#Configuration file
Version 1.0
screenW 1024
screenH 768

Source Code is displayed in different colours.

#include "eckernel.h"

//This is an example source code

int main(int argc, char *argv[])
{
EcCellId cellId;
...
return 0;
}

14
 EC2007 ECDIS Kernel Programming Guide

1.2 Trademarks
Windows XP, Windows Vista, Windows 7, Window 8 and .NET are trademarks of Microsoft
Corporation.
Linux is a trademark of Linus Torvalds.
SUSE and openSUSE are trademarks of Novell, Inc.
Red Hat and CentOS are trademark of Red Hat, Inc.
Intel is a trademark of Intel Corporation.
Sentinel is a trakemark of SafeNet, Inc.
Rockey is a trademark of SecureMetric Technology Sdn Bhd

15
EC2007 ECDIS Kernel Programming Guide

2 Background Information
The conception of the EC2007 ECDIS Kernel is to provide companies or organizations with
tools that allow them to implement their own chart display software without investing in
software development in order to meet the IHO/IMO requirements. Following this
conception, our customers will use the Kernel software to implement their specific flavour of
ECDIS or other chart display software, writing their own user interface, while using the
functions of the EC2007 ECDIS Kernel to present an electronic chart in accordance with the
standards.
SevenCs is aware that there are various ECDIS-related products: while there may be the
necessity for a pure ECDIS used by the mariner, there are Vessel Traffic Control Systems
(VTS) or military applications, e.g. combat management systems, on the market, too. The
EC2007 ECDIS Kernel is designed to meet a variety of such requirements.
SevenCs controls the quality of its products. The EC2007 ECDIS Kernel is revised at least once
a year to improve its quality and add functionality according to the experiences made while
using and testing it in ECDIS related applications and products.

16
 Supported Data Formats

3 Supported Data Formats

To ensure smooth functioning of the ECDIS Kernel any type of used data must meet the
following requirements:
• Any chart product, e.g. ENCs or ARCS, must correspond to its respective standard. For a
list of supported chart products please refer to EC2007_BackgroundInformation.
• Any S-57 file must have been provided as ISO 8211 file.
• CD-ROMs containing chart data must correspond to the ISO 9660 standard.
• Sensor data telegrams (e.g. GPS data) must correspond to the IEC 61162-1 standard.

17
EC2007 ECDIS Kernel Programming Guide

4 Getting Started
This chapter is aimed at programmers who are beginning to develop an application with the
EC2007 ECDIS Kernel SDK.

4.1 Introduction
Development Kernel versus Release Kernel:
The Development Kernel version contains debugging information to allow our customer
support to react more precisely and more quickly in case problems are reported.
Consequently, the Development Kernel is slightly slower in performance than the Release
Kernel. However, Development Kernel and Release Kernel are almost identical in
functionality and are compiled from the same source code.

4.2 Getting Help

The EC2007 ECDIS Kernel documentation comprises several documents. They are located in
%EC2007DIR%/doc (Windows) or /usr/share/doc/EC2007 (Linux).
EC2007_ProgrammingGuide.pdf: Programming instructions and guidelines.
EC2007_InstallationGuide.pdf: Installation and registration instructions.
EC2007_BackgroundInformation.pdf: General background information about chart
products and standards.
EC2007_ExamplePrograms.pdf: Description of example programs and data.
Function References ([Link]): HTML based function references. The S-63 and
WMS function references are separate from
EC2007.

4.3 Compiler Settings

Building an application with the ECDIS Kernel requires some specific compiler settings which
are listed below.

18
 EC2007 ECDIS Kernel Programming Guide

4.3.1 Windows - Visual Studio 2005/2010/2013:

Compiler Settings Debug:
Runtime Library Multi-threaded Debug DLL
Struct Member Alignment 4 Bytes
Preprocessor Definitions _WINNT_SOURCE;_USE_32BIT_TIME_T
Link with Stub Library (Debug) eckernel-5.<xx>-[Link] (xx = minor version)

Compiler Settings Release:

Runtime Library Multi-threaded DLL
Struct Member Alignment 4 Bytes
Preprocessor Definitions _WINNT_SOURCE;_USE_32BIT_TIME_T
Link with Library (Release) eckernel-5.<xx>-[Link] (xx = minor version)

4.3.2 Linux / gcc

Compiler Defines: -D_UNIX_SOURCE -D_LINUX_SOURCE
Link with Library (Debug): libeckernel-5.<xx>-[Link].<yy>
Link with Library (Release): libeckernel-5.<xx>-[Link].<yy>
where xx is the minor version and yy the sub-minor version.

4.4 Multi-threading
Many functions of the EC2007 ECDIS Kernel are not thread-safe which is explicitly mentioned
in the function references of the concerned functions.
However for the symbolization it is possible to enable the use of multi-core processors, i.e.
the symbolization of the cells is spread to a defined number of threads (see Multi-threading).

4.5 Example Programs and Data

The EC2007 ECDIS Kernel comes with some example applications and data to help getting
started with Kernel programming. For a description please refer to the document
EC2007_ExamplePrograms.

19
EC2007 ECDIS Kernel Programming Guide

5 Function Sets
The EC2007 ECDIS Kernel SDK is structured into function sets which are again divided into
groups. Each function group consists of software modules written in the programming
language C++ (with ANSI C interface to keep it compiler and platform independent) which
have been grouped together according to their basic capabilities.
A marine GIS application like ECDIS, a VTS console or an interactive chart editor can be built
using these function groups. Several other applications are possible, and it is up to the
imagination of the software engineer to use the EC2007 ECDIS Kernel for his specific
application. The EC2007 ECDIS Kernel was, however, designed with the IHO ECDIS standards
in mind, and it therefore unfolds its full potential when used in applications designed for sea-
borne vessels.
Figure 1 gives a general overview of the Kernel function sets, the SENC and Kernel databases,
and their interaction via data flow.

Figure 1: EC2007 ECDIS Kernel Function Sets

The main data flow starts with the import of chart data, provided either in ENC S-57 format
(files with extension *.000) or in SevenCs SENC format (files with extension 7CB). These chart
data are converted into a binary format and stored in the System Electronic Nautical Chart,
or SENC, database (files with extension *.7CB). All subsequent processes access the data in
the SENC together with the data in the Object Dictionary.

20
 EC2007 ECDIS Kernel Programming Guide

In order to display the chart data they have to be further prepared. The information from
the Presentation Library, the Object Dictionary, and the SENC are used to create drawing
instructions stored in the Display List. These data can be either printed or displayed on the
computer monitor.

5.1 EC27_Admin
All functions necessary to initialize, register and configure the EC2007 ECDIS Kernel are
collected in the function set EC27_Admin. See chapter Definition of the Environment and
Registration for more information.

5.2 EC27_AIS
The AIS (Automatic Identification System) has been developed for the maritime industry
using the maritime VHF band for transmission and reception of data signals. See chapter AIS
for more information.

5.3 EC27_ARINC1
This set contains just two functions to import aviation charts in the ARINC 424 format, i.e. to
convert them to the SENC format and import them into the DENC structure.

5.4 EC27_ARCS
Chart data for ECDIS are usually supplied in vector format. However, until global vector data
coverage is available there is a need to display raster information to bridge the coverage
gap.
The EC27_ARCS function set contains groups of functions for reading and displaying ARCS
raster charts, for supporting the ARCS automatic updating mechanism, and handling the
ARCS security scheme.
The function set also cooperates with the function set EC27_Draw by using the same
computer memory to prepare the chart image before copying it to the screen. This allows a
vector overlay on top of the raster chart which makes it possible to e.g. plan a route in the S-
57 vector format. See chapter ARCS for more Information.

1
The ARINC set is not available for Red Hat 5 and OpenSUSE 11

21
EC2007 ECDIS Kernel Programming Guide

5.5 EC27_BSB
The EC27_BSB function set contains groups of functions which support loading and
displaying raster charts in BSB format. The core routines are included in a set of separate
DLLs, whereas the Kernel provides an interface compatible with other function sets.

Please note:
The EC27_BSB function set is only available for Windows 32bit.

For more information see chapter BSB.

5.6 EC27_DENC
To simplify and accelerate handling of ENCs SevenCs has developed a chart management
concept called directENC. Please refer to the document EC2007_Backgroundinformation for
more details about the SENC format and the directENC concept. The entire function set is
based on a specific file based database structure, the so-called DENC structure, into which
not only the SENC files are imported but other information (referenced text and picture files,
update history files, etc.) as well.
The EC27_DENC function set consists of three function groups:
• DENC Producer Agency Code (PAC) Handling
• DENC Data Handling
• DENC Update Handling
The group DENC Producer Agency Code Handling contains functions to access the producing
agency code catalogue, which is part of the ECDIS Kernel delivery. This catalogue contains all
IHO codes for the official data producers as well as all registered codes of private data
producers.
The group DENC Data Handling contains functions to not only handle the import of charts
into the DENC structure but also the automatic loading for the visualization of SENC files in a
comfortable way.
The functions in the group DENC Update Handling are used to apply S-57 update messages
to the SENC database as well as converting S-57 base files into the SENC format.

5.7 EC27_DNC
This set provides functions to process DNC (Digital Nautical Chart) data. It includes rules and
lookup tables for the symbolization of DNC features, object and attribute dictionaries, and a
special DNC version of the danger dictionary [Link]. See chapter DNC, VMap, TOD for
more information.

22
 EC2007 ECDIS Kernel Programming Guide

5.8 EC27_Draw
After a display list has been created with the functions of the EC27_Symbol set the chart can
be displayed on several media using the EC27_Draw function set.
The EC27_Draw function set consists of three function groups:
• Chart Drawing
• Colour Handling
• Dynamic Object.
This function set contains functions that create a bitmap from the vector data of the SENC in
the computer memory at high speed. From there it can be copied to the display window.
Because the chart image is created in the computer memory before it is copied to the screen
double buffering is fully supported by the EC27_Draw function set. These functions also
support 8-bit graphics as well as true colour. See chapter Chart Drawing for more
information.

5.9 EC27_Easy
The function set EC27_Easy contains convenience functions to create a SENC with objects
and to display objects. It is not intended to be used for developing ECDIS or other complex
applications.

5.10 EC27_Globe
Most navigational systems determine the area of operation by evaluating the sensor input,
but usually it is also necessary to select an area anywhere in the world.
When determining a particular geographic area of operation it is helpful to have a graphic
globe display or a list of ports to choose from, instead of selecting a particular chart from a
list of file names.
With the functions of the function set EC27_Globe a globe with coastlines and ports can be
displayed. This globe can be rotated and areas and ports can be interactively selected. Charts
of the selected area or the surrounding area of the selected port can then be loaded into or
deleted from the SENC database.
The port database can also be realized as a list of locations. If a particular port is selected the
globe rotates to this location and the surrounding area can then be selected as the new
chart focus. See chapter Globe for more information.

23
EC2007 ECDIS Kernel Programming Guide

5.11 EC27_Monitor
A basic requirement for navigational systems is the ability to monitor the ship's movement
and give an early warning of dangerous situations. The dynamic information such as current
position, course, and speed combined with the chart data in the SENC is used to realize this
functionality.
With the functions of the EC27_Monitor set a danger alert system can be implemented.
A guard zone surrounding the ship can be defined, and the SENC is then frequently queried
to search for obstacles located in this guard zone. It is also possible to implement an alert
system that warns the user in case the ship is off the planned route.
There are also functions available to realize recording and displaying a past track, as well as
calculating a short-term prediction of the ship's motion. See chapter Monitoring for more
information.

5.12 EC27_Navigation
To navigate a ship it is necessary to calculate positions and distances. With this information
the user can plan a voyage or estimate the time of arrival.
The EC27_Navigation function set consists of the following function groups:
• Navigation Calculation
• Navigation Printout
• Time Handling
The group Navigation Calculation includes functions for calculating geographical positions,
distances and bearings. These modules can be used for route planning.
The group Navigation Printout includes modules to convert the data structure of coordinates
and distances into string type and vice versa. These modules are helpful to print this kind of
data or e.g. display it in a message box.
The group Time Handling includes modules to set and correct the displayed time, e.g. when
passing different time zones.

5.13 EC27_Print
Even when using an ECDIS some situations call for hard copies of a digital chart. If, for
example, the positioning systems in the ECDIS are unavailable or an event shall be recorded
for evidence it may be necessary to print a chart of the current area of operation.

Please note:
The printed output of a digital chart is not comparable with an original paper chart and
might miss objects which are only contained in paper charts but not in digital ones.

24
 EC2007 ECDIS Kernel Programming Guide

The EC27_Print function set consists of two function groups:

• Print X11
• Print NT
The functions in these groups differ in the operating system used as indicated by their
names.
On UNIX systems charts can be printed from the Display List contents using the function
group Print X11. The Kernel function writes a Postscript image of the bitmap or the window
to the file associated with a file descriptor. The Image is then scaled by a scale factor.
On Windows, the Kernel function on the group Print NT prints the contents of the specified
bitmap. The system's default printer selection box is used to specify the printer settings.

5.14 EC27_River
This set provides functions for the configuration of the display of IENC specific notice mark
symbols and for reading special river network information from the IENCs.

5.15 EC27_Route
A navigational system must allow to plan different routes, select an appropriate route to be
used, and check it for safety.
With the functions of the EC27_Route set a user can interactively plan a complex route
network both as great circle or rhumbline by creating waypoints and leglines. A curved
legline can be defined by specifying a turning radius at a waypoint. To select a route from
the available route network the user only needs to specify the starting point or legline, and
the system automatically searches for the next legline or waypoint to create a complete
route. The user only needs to mark the next legline if it is ambiguous.
The routes can be changed, stored, selected, and pre-checked to ensure safe passage with
regard to the chart information in the SENC. See chapter Indication of Automatic Updates
With the new editions 4.0 of the IHO Presentation Library and the IEC 61174 Standard the
mariner must be able to not only review single updated objects but also all objects which
have been updated in a certain date range. In addition not only the recent object shall be
indicated but also former states of the object, e.g. former extensions of areas.
For this reason a new type of SENC file has been introduced, the so-called SENC history file
with the extension 7UH.
The compilation of the SENC history files during the chart import has to be enabled with the
function EcS57V3SetUpdateHistoryMode.
In case ENC updates have been applied with the update history mode and SENC history files
have been compiled the updates can be reviewed with the function
EcDraw[NT][X11]HighlightUpdateHistory.

25
EC2007 ECDIS Kernel Programming Guide

An example implementation of the update indication can be found in the Qt based example
program showHistory.
Route Handling for more information.

5.16 EC27_S57
During operation an ECDIS accesses all chart information from its SENC database. The system
therefore must be capable of importing new charts or updates from official and private
sources and converting them into the binary format of the SENC database.
The EC27_S57 function set consists of four function groups:
• S-57 Dictionary Access
• S-57 Data Access
• S-57 Exchange Set
The group Dictionary Access includes functions to access the object dictionary for a certain
chart product. Please refer to the document EC2007_Backgroundinformation for more details
about object dictionaries.
Since most ECDIS Kernel functions handle objects they need object relevant information
from the object dictionary. With the function of this group an object dictionary can be read
and information extracted.
The group S-57 Data Access includes functions to read and convert single S-57 files. Using
this function group an application can read S-57 files and store the information in the SENC.
In addition the meta information of the S-57 file can be queried.

Please note:
For importing S-57 charts into the application’s chart database SevenCs recommends to
use the DENC functions (see chapter Chart Installation)

The group S-57 Exchange Set includes functions to access the S-57 catalogue file which is
contained in the IHO data exchange set.

5.17 EC27_SENC
According to the IMO/IHO specifications an ECDIS stores its charts in the SENC. The SENC is a
database which results from the conversion of the S-57 database, i.e. ENCs or other S-57
based chart products. It enables a fast display of vector chart data and queries to be
performed on the associated descriptive data.
The EC27_SENC function set consists of three function groups:
• SENC Data Handling
• SENC Data Protection
• Generic Permit Handling

26
 EC2007 ECDIS Kernel Programming Guide

• Manual Updating

Please note:
SevenCs recommends to use the DENC Data Handling functions (see chapter Chart
Loading) for standard chart display applications, and the SENC Data Handling only for
specific applications.

The group SENC Data Protection includes functions to encrypt and decrypt SENC cells.
The group Generic Permit Handling is very much linked to the group SENC Data Protection
and includes functions to manage SENC permits.
The group Manual Updating includes functions to manually update objects of the SENC data.
Existing objects can be annotated, marked as deleted or new objects can be inserted. The
SENC cells themselves are not changed, and all manual updates can be withdrawn again. See
chapter Manual Updating for more information.

5.18 EC27_Sensor
Crucial to ECDIS products is the ability to process input data from external sensors such as
GPS, AIS, gyro, speed log and ARPA-radar.
This dynamic information can then be displayed with the charts, e.g. a ship symbol indicating
the current position. It can also be processed and used by modules of other function sets,
e.g. to realize a danger alert system in combination with the function set EC27_Monitor.
The functions of the EC27_Sensor set are used to read sensor information from a serial port,
communicating in the NMEA-0183 standard data format. They are designed to be used in
independent processes, in order not to slow down the interactions with the ECDIS user
interface.
Any incoming sensor data about the state of the system, and information on interactions
between the user and the system must be recorded in order to meet the ECDIS standards.
This function set therefore also includes a group of functions to record the movement of the
own ship from the sensors. Information such as position, heading, and speed is written to a
time-stamped log file. These data can be played back from the file for analyzing vessel
movements, or for training purposes. See chapter Sensor Data for more information.

5.19 EC27_Symbol
The SENC database contains pure geometry and abstract descriptions of chart objects, or, in
other words, the chart data are stored in the SENC independent of the presentation. This
means that it is the task of the ECDIS software to render a chart display from these abstract
data.
The EC27_Symbol function set consists of three function groups:
• Chart Presentation
• Mariner Settings

27
EC2007 ECDIS Kernel Programming Guide

• Symbology Procedures
These groups contain functions to display the SENC database contents. Drawing instructions
are created from the SENC by invoking the Presentation Library Please refer to the
document EC2007_Backgroundinformation for more details. As a result a display list is created
which will be used by the functions of the EC27_Draw set. See chapter Chart Display for more
information.

5.20 EC27_Tides
This function set provides functions to calculate tidal predictions. See chapter Tidal
Predictions for more information.

5.21 EC27_Vector
The EC27_Vector function set consists of several groups needed to access information in a
SENC file. This information can be meta information and information about objects which
are defined in the SevenCs Data Model. Please refer to the document
EC2007_Backgroundinformation for more details.
In general this set contains 'get' and 'set' functions, as well as query functions, and allows
on-the-fly access, i.e. chart objects can be created and edited while the chart is displayed.
See chapter Cell Data Access for more information.

28
 EC2007 ECDIS Kernel Programming Guide

6 Core Functionality
This chapter describes the implementation of a basic chart display system, i.e. the pre-
configuration and the chart (ENC) installation, loading and display. All these functions are
mandatory for the implementation of a basic chart display system.
Specific ECDIS functions like route handling are described in chapter Specific ECDIS
Functionality.
Handling of non-ENC chart products is described in chapters Display of AIS Targets and Non-
ENC Products.

The implementation of the EC2007 ECDIS Kernel into the end user’s application can be split
into two parts. The first part deals with the pre-configuration which must run during the
initial start of the application. Mostly these are functions for the registration, reading
dictionaries and perhaps the initialization of the view.
The second part deals with the procedures which are repeated during the runtime of the
application. Mostly this relates to chart loading, symbolization and drawing.

Please note:
In this chapter in some cases only the names of the functions to be used are mentioned.
For a detailed description see the html-based function reference.

6.1 Definition of the Environment

If the environment variables have not been defined within the operating system they have
to be defined by the application, either by the EC2007 ECDIS Kernel function EcKernelSetEnv
or by system calls.
For Windows e.g.:
EcKernelSetEnv("LIB_7CS=C:/Program Files/MyECDIS/EC2007");
EcKernelSetEnv("CFG_7CS=C:/Program Files/MyECDIS/EC2007/lib/config");

For Linux e.g.:

EcKernelSetEnv("LIB_7CS=/opt/MyECDIS/EC2007");
EcKernelSetEnv("CFG_7CS=/opt/MyECDIS/EC2007/lib/config");

6.2 Registration
At start-up of the application EcKernelRegisterSetMode must be called in case the hardware Id
shall not be retrieved from the hard disk but from the network card or dongle. The following
modes can be defined for the hardware selection:

29
EC2007 ECDIS Kernel Programming Guide

EC_REGISTER_CHECK_DONGLE_7: use standard Sentinel dongle as delivered by

SevenCs
EC_REGISTER_CHECK_DONGLE_8: use standard Rockey dongle as delivered by
SevenCs
EC_REGISTER_CHECK_DONGLE_9: use network Rockey dongle as delivered by
SevenCs
EC_REGISTER_CHECK_NETCARD: use (first) network adapter
EC_REGISTER_DONT_CHECK_NETCARD: do not use network adapters
EC_REGISTER_HW_SELECT: use only selected or first source of sequence
EC_REGISTER_HW_SEQUENCE: use standard sequence for hardware detection

EC_REGISTER_HW_SELECT is turned off by default but will be turned on when using dongles
of types 8 or 9. Thus, if the dongle is not found the detection will stop and the registration
will fail without any hardware id.

Please Note:
NetRockey4ND is not supported on Linux 64bit systems.
Rockey4ND and NetRockey4ND are not supported on Windows 8.

In addition there are modes for dialog handling:

EC_REGISTER_INTERACTIVE: interactive registration mode, show dialogs

(default)
EC_REGISTER_QUIET: quiet registration mode, suppress dialogs but
show error messages
EC_REGISTER_REALLY_QUIET: quiet registration mode, suppress dialogs and
error messages

An application defined callback function can be registered with the function

EcKernelRegisterSetCallback. This function is called by the ECDIS Kernel each time a
registration dialogue or message is displayed in normal mode.
By using EcKernelRegisterGetStatus you can check whether the registration of the Kernel has
been successful. If the Kernel has not been registered yet, the SevenCs registration dialog
will be opened to enter the registration keys. Please refer to the documentation
EC2007_InstallationGuide.
The following example will only allow a registration on the network card without the fall
back to the hard disk.

30
 EC2007 ECDIS Kernel Programming Guide

EcKernelRegisterSetMode(EC_REGISTER_CHECK_NETCARD);
EcKernelRegisterSetMode(EC_REGISTER_HW_SELECT);

int status;
if (!EcKernelRegisterGetStatus(&status))
{
fprintf(stderr, "Please check your Kernel installation.
Registration status = %04X \n", status);
/* error handling */
}

In case you want to use your own dialogues for the registration procedure, SevenCs has
implemented a Registration Application Programming Interface (RAPI). This RAPI consists of
special Kernel functions that handle the Registration Key and the hardware ID. If you decide
to implement your own user interface your program has to perform the following steps for
registration:
By using EcKernelRegisterGetStatus you can check whether the ECDIS Kernel has already been
registered on your system. If not, you will have to call EcRegisterGetHardwareId to get the
hardware string which must be sent to SevenCs for getting the Registration Key. After your
program has received the Registration Key it should call EcKernelSetRegKey. The return value
of EcKernelRegisterGetStatus will indicate whether the registration has been successful.

6.3 Module Handling

EC2007 ECDIS Kernel Modules are required either for certain functionality or for the support
of certain chart products. For details please refer to the document EC2007_InstallationGuide.
The required modules have to be defined prior to the registration of the application.
According to the module key which was entered for the registration, certain modules are
enabled. To find out which modules are enabled the function EcKernelRegisterTestModule
must be called.
if (!EcKernelRegisterTestModule(EC_MODULE_S57_IMPORT))
{ /* error handling */ }

The module identifier may be one of:

Main module:
EC_MODULE_MAIN

Import modules:
EC_MODULE_S57_IMPORT
EC_MODULE_VPF_IMPORT

31
EC2007 ECDIS Kernel Programming Guide

Display modules
EC_MODULE_INLAND,
EC_MODULE_AML
EC_MODULE_DNC
EC_MODULE_VMAP
EC_MODULE_MIL2525
EC_MODULE_DTED
EC_MODULE_ARINC
EC_MODULE_3D

Function modules:
EC_MODULE_VM

6.4 Dictionary Handling

The object and attribute dictionary files of the SevenCs EC2007 ECDIS Kernel (please refer to
the document EC2007_BackgroundInformation) must be read into the computer's memory
before accessing the information. The structure of this memory is not visible to the user. The
pointer to the so-called 'dictionary context' must be passed to all functions needing access to
one of the dictionaries.
The function EcDictionaryReadModule which returns this dictionary context must be called
before calling any other functions needing a parameter of type EcDictInfo*.
Example for reading the dictionaries for ENCs and IENCs:
EcDictInfo *dictInfo;
UINT32 module = EC_MODULE_MAIN | EC_MODULE_INLAND;
if ((dictInfo = EcDictionaryReadModule(module, NULL)) == NULL)
{ /* error handling */ }

...

EcDictionaryFree(dictinfo);

Whenever the dictionary context is not used anymore, it must be freed by calling the
function EcDictionaryFree. Usually this is when the application quits.
For all functions which access the dictionaries, LIB_7Cs must be defined. The functions
access the dictionaries from $LIB_7CS/lib/objcat.

32
 EC2007 ECDIS Kernel Programming Guide

According to the modules which were defined, following dictionary files will be loaded:

EC_MODULE_MAIN ENC20EN[O|A].7DI ENC 2.0

S5731EN[O|A].7DI S-57 3.1 (prohibited for ENCs)
MIO32EN[O|A].7DI S-52, mariners objects
7CS10EN[O|A].7DI SevenCs application
NAV14EN[O|A].7DI Navionics
AIO20EN[O|A].7DI Admiralty Information Overlay
EC_MODULE_INLAND INL10EN[O|A].7DI IENC 1.02
INL23EN[O|A].7DI IENC 2.3
EC_MODULE_AML AMLCLB10EN[O|A].7DI AML CLB 1.0
AMLESB10EN[O|A].7DI AML ESB 1.0
AMLLBO10EN[O|A].7DI AML LBO 1.0
AMLMFF10EN[O|A].7DI AML MFF1.0
AMLRAL10EN[O|A].7DI AML RAL 1.0
AMLSBO10EN[O|A].7DI AML SBO 1.0

AMLCLB21EN[O|A].7DI AML CLB 2.1

AMLESB21EN[O|A].7DI AML ESB 2.1
AMLLBO21EN[O|A].7DI AML LBO 2.1
AMLMFF21EN[O|A].7DI AML MFF2.1
AMLRAL21EN[O|A].7DI AML RAL 2.1
AMLSBO21EN[O|A].7DI AML SBO 2.1
EC_MODULE_DNC DNC10EN[O|A].7DI DNC
TD010EN[O|A].7DI TOD 0
TD110EN[O|A].7DI TOD 1
TD210EN[O|A].7DI TOD 2
TD410EN[O|A].7DI TOD 4
MAT10EN[O|A].7DI MATT
EC_MODULE_VMAP VMP10EN[O|A].7DI VMap
EC_MODULE_MIL2525 M25B2EN[O|A].7DI Mil 2525 (UIE objects)
EC_MODULE_ARINC AVI10EN[O|A].7DI Aviation objects2

If you want to create your own object classes and attributes the function
EcDictionaryMergeExt must be used. Please refer to chapter 9.9 User-Defined Chart Objects.

2
The ARINC module is not available for Red Hat 5 and OpenSUSE 11

33
EC2007 ECDIS Kernel Programming Guide

6.5 Chart Installation

Before any chart can be displayed it must be installed to the application’s internal chart
database. Independent of the chart product, all S-57 vector data are converted to the
SevenCs SENC format. ARCS and BSB are just copied into the internal chart database.
The functions described in the following chapters are based on the directENC concept
(please refer to the document EC2007_BackgroundInformation for details) which allows an
automated chart installation for standard chart display application like ECDIS or VTS.
In case of specific chart display applications where only certain ENCs have to be imported
the EC2007 ECDIS Kernel provides low level functions. Please refer to chapter 12.1 for
details.

Please note:
SENC cells which are currently loaded into the view, must not be updated (Please refer to
chapter 6.5.4 General Chart Import).

6.5.1 Chart Provision

Official ENCs are produced by Hydrographic Offices and distributed by so-called Regional
ENC Centers (RENC), e.g. IC-ENC or Primar. In addition the UKHO provides their ENCs but
also ENCs from other countries within their Admiralty Vector Chart Service (AVCS). All of
these RENC and UKHO have their so-called Value Added Resellers (VAR). ChartWorld
([Link]) is a VAR which not only has the approval to distribute the ENCs in S-
63 but also in the SevenCs SENC format, which is called directENC. In that case the S-57 or S-
63 Import is already done on distributor’s side and therefore safes a lot of time on the end
user’s application and simplifies and accelerates the chart installation significantly.
For general information about the directENC concept and the different chart formats S-57, S-
63 and SENC please refer to the document EC2007_BackgroundInformation.

6.5.2 DENC Structure

The DENC structure is the main part of the directENC concept. It must be created and
initialized before any functions of the EC2007 Function Set EC27_DENC can be used.
An example implementation of the DENC structure can be found in the WIN32 example
program denctest or the Qt based example program showDENC.

[Link] Creation of DENC Structure

The function to create a DENC structure and the standardized directory structure is called
EcDENCCreate. The parameters are:
• di pointer to a dictionary context
• path location of <DENC_ROOT> directory (will be created if it does not already
exist)
• forceFlag catalogue overwrite flag

34
 EC2007 ECDIS Kernel Programming Guide

This function creates a new DENC structure in memory and reads the producer agency
catalogue if it exists. If a cell catalogue exists in the specified path it is used, otherwise a new
cell catalogue is created. To force the creation of a new cell catalogue the third parameter
can be set to True. The return value of this function is a pointer to the new EcDENC
structure. If the structure is no longer used it should be deleted by the application using the
function EcDENCDelete. If the function fails NULL is returned, and the error can be retrieved
with the help of the function EcKernelGetLastError.

[Link] DENC Directories and Files

Following files exist in the main DENC directory:
• CATALOG.7CC SENC catalogue (see chapter SENC Catalogue)
• [Link] Installation passport (see chapter Installation Passport)
• PRODCODE.7CA Producer agency catalogue (see chapter Producer Agency Catalogue)

Following sub-directories exist:

• CELLS Basic path for SENC cells and history files (7CB, 7CT, 7CH)
• PACKAGES Contains reference cells (7CR)
• PERMITS Contains PAK files (7CK)
• TEMP Contains temporary files, e.g. during package installation
• TIF Basic path for image files and multimedia files (TIF, GIF)
• TXT Basic path for text files (TXT)
• UPDATES Basic path for ENC cells and update files (000, 001, ...)
The subdirectories CELLS, TXT, and TIF all have further subdirectories. The name of each
subdirectory is derived from the name of the corresponding SENC file, text, or picture file,
respectively.

Example:
The SENC file 7C3ABCDE.7CB will be stored in the path CELLS/7C/3A/BC/DE.
The TEXT file [Link] will be stored in the path TXT/7C/12/34/56.

The following file types may exist within a DENC directory structure:
• 7CA Producer agency catalogue
• 7CB SENC file
• 7CC Cell catalogue
• 7CR Reference cell
• 7CP directENC Package access key (PAK) file
• 7CK directENC Package access key (PAK) archive
• 7CX directENC Package

35
EC2007 ECDIS Kernel Programming Guide

• 7CH ASCII history file

• 7UH SENC history file
• 000..999 S-57 file (base and update)
• TXT Text file
• HTM HTML file
• DOC Document

[Link] DENC Structure Handling

To determine the correct location of a file in the directENC directory structure the function
EcDENCGetPath can be used. The parameters are:
• denc Pointer to an EcDENC structure
• cellname File name to get path for (without path)
• cellPath Full path including file name
• maxPathLen Size of cellname buffer
• create Flag for creating returned path
If the last parameter is set to True the function creates all subdirectories required to reach
the correct location of the specified file. The filename specified by cellname must follow the
directENC naming conventions and must not contain any path. This function returns True on
success and False otherwise. If an error occurred the function EcKernelGetLastError can be
used to determine its cause.
To delete all files of a directENC structure and the corresponding directory structure the
function EcDENCDeleteTree can be used. The parameters are:
• denc Pointer to EcDENC structure
• di Pointer to object catalogue context
This function invokes the callback function which can be set with EcDENCSetCallback (see
chapter [Link]) for every file in the directory tree. If the callback returns True, all files in the
corresponding directory will be deleted as well as the directory itself. If any files remain in
the structure, the cell catalogue will be updated. If all files are deleted, the base directory
will also be removed, and the EcDENC structure should be freed using EcDENCDelete.

[Link] DENC Callback Function

The callback function which is invoked by the import, delete, and update functions can be
set using the ECDIS Kernel function EcDENCSetCallback. The parameters are:
• denc Pointer to EcDENC structure
• callback Pointer to callback function
This function installs a callback function which is called when importing, deleting or updating
files from the EcDENC structure. To uninstall the function, specify a NULL pointer for the
callBack parameter. If the callback function returns False the file will not be added, removed,
or updated respectively. The parameters for the callback function itself are:
• denc Pointer to EcDENC structure

36
 EC2007 ECDIS Kernel Programming Guide

• filename File name including path

• reason Reason for calling the function (see below)
Possible values for the parameter reason are:
• EC_DENC_IMPORT
• EC_DENC_DELETE
• EC_DENC_UPDATE
These values can be checked to decide if the respective action should be taken for the
particular file or not. Additional values for the parameter reason are:
• EC_DENC_IMPORT_ERROR
• EC_DENC_UPDATE_APPLIED
• EC_DENC_UPDATE_REJECTED
• EC_DENC_UPDATE_WRONG_UPDN
• EC_DENC_UPDATE_WRONG_EDTN
• EC_DENC_UPDATE_NO_CELL
These values can be checked to evaluate the results of the respective action.
The function EcDENCSetCallbackExt can be used to install a callback function that takes an
additional user parameter. The usage of this function is similar to EcDENCSetCallback. A
Pointer to (static) user-defined data may be specified which will then be passed to the
installed callback. The user data buffers should be static in order to keep their contents while
the callback function is executed. In case no user data are needed, a NULL pointer may be
specified.
It is also possible to install two callback functions by calling first EcDENCSetCallback, and
then EcDENCSetCallbackExt.

Please note:
Callbacks installed with EcDENCSetCallback must be removed with the same function but
with a NULL pointer to the callback function. Callbacks installed with
EcDENCSetCallbackExt must only be removed with EcDENCRemoveCallbackExt.

The catalogue is then automatically updated whenever charts or updates are added or
removed from the chart database with one of the import functions described in the
following chapters.
To access the information of the Catalogue file, the catalogue list is used. This list is an
auxiliary structure that serves as a link between the cell catalogue and the functions used to
load cells into the view (see chapter 6.6.4) or perform route checks (see chapter 7.3).
This catalogue list can be created with the function EcDENCGetCatalogueList.

[Link] Installation Passport

The installation passport file contains information about the individual installation. Besides
information about the Operating System, OS Version, EC2007 Kernel Version, environment
settings, etc. the file holds the required hardware ID. This has not only been used for the

37
EC2007 ECDIS Kernel Programming Guide

software registration but is also required by the directENC distributor for the generation of
the directENC Package Access Keys (PAK).
To write the Installation Passport EcDENCCreateInstallationPass must be called. The default
name of this ASCII file is [Link].

[Link] Producer Agency Catalogue

Each S-57 Chart contains a producer agency code (PAC) in the cell header (see chapter 11.2).
for the handling of the producer codes, e.g. translating the token into the producer name,
the EC2007 ECDIS Kernel supplies a table with the file PRODCODE.7CA. This file is located in
$EC2007DIR/data/codes. It has to be imported into the DENC structure with EcDENCImportFile.
After the file has been imported the PAC can be accessed with EcDENCGetAllPACEntries. The
token can then be translated with EcDENCGetPACEntryByCode. To get all PACs of the installed
charts EcDENCGetInstalledPACEntries can be used.

6.5.3 SENC Catalogue

The SENC database consists of cells in the SevenCs binary format which are stored in a
directory tree. The root of this directory tree holds a special cell including information about
the coverage and usage of all cells in the SENC database. This cell is called the SENC
catalogue or cell catalogue.
The aspect of loading cells is separated into the selection of cells for their visualization, and
the selection of cells for data queries. The latter is, for example, needed for the so-called
anti-grounding (see chapter 7.6.3) or the route check (see chapter 7.5.5).
The SENC catalogue will be generated automatically by the function EcDENCCreate.

6.5.4 General Chart Import

For S-57 based vector charts SevenCs provides two function sets for loading charts:
• High level function set EcDENC*, which takes control of storing the files at the right place.
• Low level function sets EcS57* and EcS63 where all file locations must be set by the
application.
By using the EcDENC* functions the creation of the chart database is entirely managed by the
Kernel. This comprises the creation of the directory structure but also the update history
functionality. For standard applications like ECDIS or VTS SevenCs recommends to use the
EcDENC* functions which are described in the following chapters.
At certain predefined moments the EC2007 ECDIS Kernel will call special callback functions
(see chapter [Link] DENC Callback Function). They are used in order to keep the process of
chart import as flexible as possible.
The low level functions are described in chapter Manual Chart Installation.

Please note:
SENC cells which are currently loaded into the view, must not be updated. Either
- all cells have to be unloaded from the view with EcChartUnloadView (no further
operation possible), or

38
 EC2007 ECDIS Kernel Programming Guide

- the update process has to run on a copy of the DENC structure, to which the application
has to switch after the update process with EcDENCCreate, or
- during the updating process it has to checked by means of a callback function, if a cell is
loaded and therefore has to be unloaded from the view.

6.5.5 directENC Packages

A directENC package (extension 7CX) contains protected or unprotected SENC files plus
(optional) text and multimedia files which are grouped according to either geography or
topic. Packages may overlap, and may contain data from several manufacturers. The files
belonging to one package are delivered as packed archive.
To install a package a valid directENC Package Access Key (PAK) must be available, or must
have been installed already. Normally, the PAK is delivered as PAK archive (extension 7CK)
along with the package, and is installed automatically.
When a package is identified (by means of the extension 7CX) it is first checked whether it
contains a file carrying the extension PID. If so, the name of the respective file is interpreted
as protID, and an already installed PAK for this protID is looked for. If such PAK cannot be
found the directory containing the package (7CX) and the set PAK search path are searched
for all PAK archives (7CK), and these archives are installed. Then a PAK matching the protID
mentioned above is searched.
If still no matching PAK can be found the package is rejected.
If, however, a matching PAK is found it is checked whether another version of the respective
package has been installed yet. This is done by means of the reference cell (7CR).
If the directory PACKAGES already contains a file of the same name it is assumed that the
package (or another version of the package) has been previously installed. In this case the
user is given the opportunity (by means of the Callback mechanism) to decide whether the
package shall be installed nevertheless, or shall be rejected.
In case the package contains PAKs (7CP) these will be unpacked first (in the TEMPPERM
directory), and then installed. The other files of the package are unpacked in the TEMP
directory, and afterwards installed separately.
If the package contains a reference cell (7CR) this is installed in the PACKAGES directory.
To import directENC packages or directENC PAKs into the DENC directory structure the
functions EcDENCImportFile or EcDENCImportTree can be used. The function EcDENCImportFile
is used to import a single file. The parameters are:
• denc Pointer to EcDENC structure
• di Pointer to object dictionary context
• fullName File name including path
This function imports a file into the DENC structure. Before the file is added, the callback
function, if any has been set with EcDENCSetCallback, is invoked with the parameter reason
set to EC_DENC_IMPORT. If the callback returns True the import procedure will copy the

39
EC2007 ECDIS Kernel Programming Guide

specified file to the correct location within the DENC structure, and will update the cell
catalogue.
To import all files contained in a specific directory and all its subdirectories the function
EcDENCImportTree can be used. The parameters are:
• denc Pointer to EcDENC structure
• di Pointer to object dictionary context
• path Top-level directory of tree
This function steps recursively through the specified tree and calls EcDENCImportFile for each
file in the directory tree. This implies that for each file the callback function (if any is set) is
invoked with EC_DENC_IMPORT before it is copied into the DENC structure.

Please note:
In case of the use of EcDENCImportFile the directENC PAKs have to be installed before the
chart packages. In case of EcDENCImportTree this is done automatically.

There is a set of functions EcDENCGet… with which certain information about the installed
packages and PAKs can be retrieved. For details please refer to the function reference.

6.5.6 SENC Files

SENC files are imported with the functions EcDENCImportFile or EcDENCImportTree.
Before a protected SENC file can be imported the validity period of the associated PAK,
edition and update number of the cell are determined. If no valid PAK is installed the cell is
rejected. Then it is checked whether another version of that cell has already been installed.
If so, PAK validity period, edition and update number of the installed cell are determined. In
case edition and update number match the cell with the shorter PAK validity period is
installed or kept, respectively, otherwise the cell with the higher edition or update number
(in case the edition numbers match). After this the history file and the cell catalogue are
updated.

6.5.7 S-57 Files

S-57 base and update files are generally unprotected and can be imported into the DENC
structure with the functions EcDENCImportFile or EcDENCImportTree. With these functions the
S-57 files are copied to a special directory (UPDATES) where they are kept for future
conversions into SENC format (see chapter Applying S-57 Updates).

6.5.8 S-57 Exchange Sets

At the beginning of the ECDIS development unprotected S-57 charts were provided as S-57
Exchange Sets. Nowadays only rarely S-57 Exchange Sets are used. They can be imported
into the DENC structure with the function EcDENCImportS57ExchangeSet. The parameters are:

40
 EC2007 ECDIS Kernel Programming Guide

• denc Pointer to EcDENC structure

• di Pointer to an object dictionary context
• path Toplevel directory of a S57 exchange set (usually ENC_ROOT, must contain the
catalogue file CATALOG
• callBack Callback function pointer (if any had been created before with
EcDENCSetCallback)
• lowerCase Flag indicating file names are lower case
The return value is the number of imported files.

6.5.9 S-63 Exchange Sets

Unlike at the beginning of the ECDIS development charts nowadays are provided according
to the S-63 Standard, i.e. as encrypted and signed S-57 files (for details please refer to the
document EC2007_BackgroundInformation). They have to be converted into the SevenCs SENC
format before they can be used and displayed. This conversion process is performed only
once during the data import and comprises the decryption to S-57 format, the
authentication and finally the conversion into the SevenCs SENC format. The SENC file will
finally be locally protected, i.e. the SENC protection depends on the SevenCs Hardware Id
which has been used for the software registration (see Installation Guide and chapter
Registration).
The conversion process can take about a minute for one chart up to a few hours for whole
set of charts for global coverage.

[Link] EC2007 S-63 Interface

This interface is provided as a separate shared library ([Link]). It provides a set of
functions that allow to decrypt and import the originally encrypted ENCs. A Kernel
registration including the S-57 import option is required for the S-63 interface to work.
The same programming conventions as for the EC2007 ECDIS Kernel apply to the S-63
interface. It cannot be used without the ECDIS Kernel because it utilizes some Kernel
functions. Make sure to always use the Kernel version that the S-63 library was delivered
with.
An example implementation of the S-63 function set is given in the program s63test. This
can be run either with the high level functions or the low level functions. For the latter ones
scripts are provided for running the S-64 tests.
The S-63 Interface of the EC2007 ECDIS Kernel includes software developed by the OpenSSL
Project for use in the OpenSSL Toolkit ([Link]

Please note:
The EC2007 S-63 Interface offers a low level function set and a high level function for the
S-63 data import. The low level function set should be used in case of an ECDIS type
approval which requires certain error messages and user interaction. This function set is
described in the following chapters. The high level function is described at the end.

41
EC2007 ECDIS Kernel Programming Guide

An example implementation of the S-63 function set is given in the program s63test. This
can be run either with the high level functions or the low level functions. For the latter ones
scripts are provided for running the S-64 tests.

[Link] S-63 User Permit

The S-63 User Permit has to be determined by the application by means of the:
• Manufacturer Key and Identification (ID), provided by the IHO after the OEM approval
and the
• S-63 Hardware Identification (ID), generated by the application. The S-63 hardware Id is a
5 digit hexadecimal number and must be unique.
The S-63 User Permit can be created with the function EcS63CreateUserPermit. The
parameters are:
• hwId Hardware ID (HW_ID, 5 Bytes)
• manKey Manufacturer key (M_KEY, 5 Bytes)
• manId Manufacturer ID (M_ID, 2 Characters)
• userPermit Returned S-63 User permit (28 Characters)
A given S-63 User Permit can be decrypted with the function EcS63DecryptUserPermit.

[Link] Scheme Administrator (SA) Certificates

Besides the official SA certificate of the IHO with the filename [Link] there is still one RENC
operating with its own certificate. This is PRIMAR and their certificate has the name
[Link].
Usually the SA certificates are delivered together with the data carrier. However, the
application should allow to explicitly load certificates into the system. If a check with a
certain certificate fails other available certificates should be checked as well.
Information about a certificate can be queried with a set of functions which comprises:
• EcS63GetSAPublicKey
• EcS63X509CheckExpiryDate
• EcS63X509GetSerialNumber
• EcS63X509GetString
• EcS63X509GetVersion

[Link] Cell Permit Handling

Due to the new requirements in edition 3 of IEC 61174 an application must frequently check
if an S-63 cell permit is still valid or if it has expired. For that reason S-63 cell permits must be
available during runtime of the application. Within the application all permits are stored in a
permit list which is initially created once at the start of the application with the function
EcChartPermitListCreate.
The S-63 Cell Permits are read into the permit list with the function
EcS63ReadCellPermitsIntoPermitList. The parameters are:
• permitList Pointer to permit list

42
 EC2007 ECDIS Kernel Programming Guide

• permitFileName The file containing the encrypted cell permits (PERMIT

• hw_id S-63 Hardware ID (5 bytes)
• replaceFlag True
• permitCallback Pointer to callback function
• callbackData Pointer to callback data
To fulfill the ECDIS type approval requirements the callback functions have to be used in
order to receive the expected error messages concerning single permits. For non-ECDIS
application there is no need to use the callback function.
The permit list is not automatically locked while it is accessed. When the list is going to be
changed, modified, or deleted it should be de-activated first by calling the function
EcCellSetChartPermitList with a different permit list or a NULL pointer. After the modification
the permit list can be activated again with the same function.
To keep all previously installed S-63 cell permits the content of the internal permit list must
be stored with the function EcS63WriteCellPermitsToFile, when the application quits and read
again during the start of the application.

[Link] Detection of Encrypted Data

In order to detect whether the ENCs in an exchange set are encrypted or not the function
EcS63GetExchangeSetType should be used. If it returns EC_EXCH_TYPE_S63 the exchange set
contains encrypted ENCs. It is not possible to determine just from one single ENC file
whether it is encrypted or not.

[Link] Reading S-63 cells

The following functions must be processed for each single S-63 cell, i.e. within a loop over all
cells of an S-63 Exchange Set. To retrieve information about the single cells the functions of
the EcDENCExchangeSet* function set can be used.
Before an encrypted S-63 cell can be processed it must be checked if there is a valid permit
for the cell. This is done with the function EcChartGetPermitsByName. The parameters are:
• permList Pointer to permit list
• nameOrPid Name or protection Id of a cell
• permType Type of permit
• permitInfos Pointer to array of permit info structures
On success the cell can be further processed, i.e. authenticated and decrypted.

Authentication (Checking the Signature)

The signature of an ENC should be checked in order to make sure the ENC has not been
modified unauthorizedly. This check is technically independent from the decryption, so in
theory it could be skipped. However, the S-63 standard requires executing this check before
the ENC is decrypted.
The signature is checked by the function EcS63CheckSignature. The parameters are:
• certFile Filename (either [Link] or [Link]) of certificate in X509 format
• sigFile The signature file containing the ENC specific DP Certificate

43
EC2007 ECDIS Kernel Programming Guide

• encFile Name of the encrypted ENC file (including path)

In case of a failure an ERROR_SSE error code is returned.
Before the SA certificate is used it should be checked whether it is still valid. This can be
done by the function EcS63X509CheckExpiryDate.
The name of the encrypted ENC file is optional. If it is set to NULL the ENC is not
authenticated against the signature.
The name of the ENC signature file can be retrieved using the function
EcS63GetSignatureName.

Decryption
The decryption of an S-63 is done with the function EcS63ReadCell. The parameters are:
• s63FileName Name of the encrypted ENC file (including path)
• permitInfo Pointer to permit info structure containing a valid cell permit
• hw_id Hardware Id of the system (5 bytes)
• destDir Destination directory for the decrypted/converted file
• dictInfo Pointer to dictionary context
• checkCrc Pointer to CRC value from exchange set catalog (may be NULL)
• errlog Open file handle for error messages (may be NULL)
• percentFunc Callback function (called by EcS57V3ReadFileExt, may be NULL)
• outputFileName Returned pointer to name of decrypted file (may be NULL)
This function decrypts the cell with the passed cell permit and performs a CRC check if the
parameter checkCrc is not NULL. Finally it converts the S-57 cell into SENC.
The permitInfo structure is not the same as the general permit list (see Cell Permit Handling)
and has to be compiled by converting the general permit list to the permitInfo strucutre. An
example is given in the sample program s63test.
In case of a failure an ERROR_SSE error code is returned.
After the decryption the SENC files can be imported into the DENC structure with the
functions EcDENCImportFile or EcDENCImportTree.
In case of ECDIS developments the DENC callback (see DENC Callback Function) should be
used to provide the requested error messages.
The decrypted S-57 update files have to be applied with the update functions
EcDENCCheckUpdates and EcDENCApplyUpdates (see chapter Applying S-57 Updates).

[Link] S-63 Error Messages

In case of ECDIS developments following S-63 error or warning messages must be handled.
Please note that some only concern data servers, i.e. chart providers.

Error Code Error/Warning Message Implementation

SSE 01 Self Signed Key is invalid Data Server
SSE 02 Format of Self Signed Key file is Data Server

44
 EC2007 ECDIS Kernel Programming Guide

incorrect
SSE 03 SA Signed Data Server Certificate is Data Server
invalid
SSE 04 Format of SA Signed DS Certificate is Data Server
incorrect
SSE 05 SA Digital Certificate (X509) file is not Application
available. A valid certificate can be EcS63X509CheckExpiryDate
obtained from the IHO website or
your data supplier
SSE 06 The SA Signed Data Server Certificate EcS63CheckSignature
is invalid. The SA may have issued a
new public key or the ENC may
originate from another service. A new
SA public key can be obtained from
the IHO website or from your data
supplier
SSE 07 SA signed DS Certificate file is not EcS63CheckSignature
available. A valid certificate can be
obtained from the IHO website or
your data supplier
SSE 08 SA Digital Certificate (X509) file EcS63X509CheckExpiryDate
incorrect format. A valid certificate
can be obtained from the IHO website
or your data supplier
SSE 09 ENC Signature is invalid EcS63CheckSignature

SSE 10 Permits not available for this Data Application

Server. Contact your data supplier to (see s63test sample program)
obtain the correct permits.
SSE 11 Cell Permit file not found. Load the EcS63ReadCellPermits
permit file provided by the data
supplier.
SSE 12 Cell Permit format is incorrect. EcS63ReadCellPermits
Contact your data supplier and obtain EcS63DecryptCellPermitExt
a new permit file.
SSE 13 Cell Permit is invalid (checksum is EcS63ReadCellPermitsIntoPermitList
incorrect). Contact your data supplier EcS63DecryptCellPermitExt
and obtain a new permit file.
SSE 14 Incorrect system date, check that the Application
computer clock (if accessible) is set
correctly or contact your system
supplier.
SSE 15 Subscription service has expired. EcS63CheckCellPermitExpiryDate

45
EC2007 ECDIS Kernel Programming Guide

Please contact your data supplier to

renew the subscription licence
SSE 16 ENC CRC value is incorrect. Contact EcS63ReadCell
your data supplier as ENC(s) may be
corrupted or missing data.
SSE 17 Userpermit is invalid (checksum is Data Server
incorrect). Check that the correct
hardware device (dongle) is
connected or contact your system
supplier to obtain a valid userpermit.
SSE 18 HW_ID is incorrect format Data Server
SSE 19 Permits are not valid for this system. EcS63DecryptCellPermitExt
Contact your data supplier to obtain
the correct permits
SSE 20 Subscription service will expire in less EcS63CheckCellPermitExpiryDate
than 30 days. Please contact your
data supplier to renew the
subscription licence
SSE 21 Decryption failed no valid cell permit EcS63DecryptUserPermit
found. Permits may be for another EcS63DecryptCellPermit
system or new permits may be EcS63DecryptCell
required, please contact your supplier EcS63ImportExchangeSetExt
to obtain a new licence

SSE 22 SA Digital Certificate (X509) has EcS63X509CheckExpiryDate

expired. A new SA public key can be
obtained from the IHO website or
from your data supplier.
SSE 23 Non sequential update, previous Callback of DENC import functions
update(s) missing try reloading from
the base media. If the problem
persists contact your data supplier.
SSE 24 ENC Signature format incorrect, Equals SSE 09
contact your data supplier

SSE 25 Viewer – “The permit for ENC<cell Application

name> has expired. This cell may be
out of date and MUST NOT be used
for Primary NAVIGATION”.
SSE 26 This ENC is not authenticated by the EcS63CheckSignature
IHO acting as the Scheme
Administrator
SSE 27 Viewer – “ENC<cell name> is not up Application
to date. A New Edition, Re-issue or

46
 EC2007 ECDIS Kernel Programming Guide

Update for this cell is missing and

therefore MUST NOT be used for
Primary NAVIGATION”.

[Link] S-63 Meta Information

S-63 Exchange Sets according to version 1.1 of S-63 contain additional meta information,
which are necessary to fulfill the S-63 requirements for ECDIS. The information are stored in
the S-63 file [Link] and [Link]. [Link] contains general information about
the Exchange Set and [Link] general information about the chart portfolio of the
data server, i.e. the chart provider.
To read general information about the Exchange set the function EcS63ReadExchangeSetInfo
can be used.
For the handling of the information of the [Link] following functions can be used:
• EcS63CreateProductsCatalog
• EcS63FreeProductsCatalog
• EcS63ReadProductsCatalog
• EcS63GetProductsCatalogInfo
With these functions following requirements can be fulfilled:
• Report cells which have been cancelled and/or replaced by new cells. (IHO S-63/64
requirement)
• Notify the user if any newer editions of a cell are available than the one which is in the
system

[Link] High level S-63 Handling

In case of non-ECDIS developments the high level function EcS63ImportExt might be used. In
that case only the main error numbers are given in case of a failure.

6.5.10 Applying S-57 Updates

After importing S-57 files/Exchange Sets and S-63 Exchange Sets the update functions
EcDENCCheckUpdates and EcDENCApplyUpdates must be called to convert the S-57 files into
the SENC format, apply any updates, and copy the cells into the respective directories of the
DENC structure.
To check if any new S-57 base cells are available or if any updates can be applied the
function EcDENCCheckUpdates is used. The parameters are:
• denc Pointer to EcDENC structure
• di Pointer to object dictionary context
This function checks the update directory of the DENC structure for new S-57 base or update
files. The return value of this function is the number of files which can be applied or -1 if an
error occurred. The files are moved into the respective directories of the DENC structure. All
S-57 base, new edition, and reissue files are moved so that they can be imported using the
function EcDENCApplyUpdates. The update files are checked with respect to their edition and

47
EC2007 ECDIS Kernel Programming Guide

update number. If an update is rejected - wrong update or edition number, or corresponding

base cell not found - a corresponding entry will be made in the history file in the update
directory. Base or update files that have already been applied will be deleted, and a
corresponding entry will be made in the history file. This function also invokes the import
callback (see chapter DENC Callback Function), provided it has been set.

Please note:
The function EcDENCApplyUpdates should be called before calling the function
EcDENCCheckUpdates again in order to minimize the chance of update files from different
editions but with same update numbers overwriting each other.

To convert any S-57 base files or apply any update files the function EcDENCApplyUpdates can
be used. The parameters are:
• denc Pointer to EcDENC structure
• di Pointer to object dictionary context
This function converts the S-57 cell files into the SENC format and applies the update files in
the respective update directory of the DENC structure. The files that can be applied are
moved into this directory by the function EcDENCCheckUpdates. The function also invokes the
callback, if any has been set, when an update has been successfully applied with the
parameter reason set to EC_DENC_UPDATE_APPLIED. All changes made by an applied
update are recorded in the cell’s history file. These changes can be retrieved from the
history file by using the function EcDENCGetUpdateInfo. The return value of the function
EcDENCApplyUpdates is the number of successfully converted base cells and applied updates,
or -1 if an error occurred.

6.5.11 Retrieving Update Information

To retrieve information about the changed objects of a specific cell the function
EcDENCGetUpdateInfo is used. The parameters are:
• denc Pointer to EcDENC structure
• cellName Name of the base cell (no path required)
• updInfo Pointer to array containing update information
• infoNum Number of entries in array updInfo
This function reads the history file of the specified cell and stores all update information, if
any is available, in an array of EcUpdateInfo structures. Each entry of this array represents a
changed object. The corresponding update number, issue date, and apply date are also
stored in the EcUpdateInfo structure for each object. The last parameter gives the number
of changed objects (elements of the array updInfo).

Please note:
This function allocates memory for the array of update information which, if the number
of elements infoNum is greater than 0, must be freed by the application using the
function EcFree.

48
 EC2007 ECDIS Kernel Programming Guide

If a special update has been applied (announcing that a new edition is available, or to
remove a complete data set) this information will be stored in an entry of the array updInfo,
too. The member info then contains the respective information. However, all other
members are 0 or empty strings.
The structure EcUpdateInfo can be accessed to visualize modifications of the cell made while
updating it. This structure has the following data fields:
• featName S-57 record ID of updated feature
• action “inserted”, “deleted” or “modified”
• objClass Six character object class code of updated feature
• info Content of attribute updmsg if set for updated feature
• lat / lon Estimated center position of updated feature
• recId Record id of feature object
• edtNum Edition number
• updNum Update number
• applyDate Date the update was applied (yyyymmdd)
• applyTime Time the update was applied (seconds since midnight)
• issueDate Issue date of update (yyyymmdd)
• specialUpd Indicating a special update
The member specialUpd is set in case a base cell has been converted or a special update has
been applied. The values can be:
• EC_UPDATE_BASE_CELL
• EC_UPDATE_EDITION_AVAIL
• EC_UPDATE_REMOVE_CELL.
In all three cases the other members concerning the updated object are 0 or NULL. So the
member specialUpd should be checked before using the values of the others.
The dates of the members applyDate and issueDate are stored as a long values with the
following format: YYYYMMDD, making it easy to compare two dates.

6.5.12 Deleting Charts

Normally charts should not be deleted manually. If a chart is not valid anymore the chart
producer has to create a delete message which is contained in an S-57 update file. If such
update file is imported and applied with the functions mentioned above, the respective base
file will be automatically removed from the DENC directory structure. However, there are
functions to delete charts manually as well.

[Link] directENC Packages

Complete direct ENC Packages can be deleted with EcDENCDeletePackage. The parameters
are:

49
EC2007 ECDIS Kernel Programming Guide

• denc Pointer to EcDENC structure

• di Pointer to dictionary info
• packageName Package name (without path and extension)
This function deletes a package from the directENC structure. All cells belonging to the
specified package are deleted provided they are not referenced by other packages. Cells that
belong to other packages as well are not deleted.

[Link] Single Charts

It is not only possible to add files to a DENC structure but also to remove them from such
structure. The function EcDENCDeleteFile is used to remove a single file from a DENC
structure. The parameters are:
• denc Pointer to EcDENC structure
• di Pointer to object dictionary context
• filename File name (no path required)
This function removes a file from the DENC structure. Before the file is deleted the callback
function, if any has been set with EcDENCSetCallback, is invoked with the parameter ‘reason’
set to EC_DENC_DELETE. If the callback returns True the delete procedure will remove the
specified file from the DENC structure and update the cell catalogue. The parameter
filename must specify a valid directENC file.

Please note:
When single cells are deleted it is not checked which package they belong to. If a deleted
cell is referenced by a package reference cell this could lead to inconsistencies. That is
why only those cells should be deleted separately which are not parts of an installed
package.

6.5.13 ACES
ACES (Advanced ChartWorld ENC Service) is a service of SevenCs’s sister company
ChartWorld. It is an approved SENC distribution service which is available for UKHO AVCS
and AIO data. ACES Exchange Sets are constructed like S-63 Exchange Sets. The only
differences is that they do not contain S-63 charts but preprocessed SENC charts which
dramatically reduces the loading time and lead to easier installation routines and less data
transfer.
Due to the similarity with S-63 Exchange Sets and permits the same functions can be used.
Please refer to chapter.

6.5.14 ARCS / BSB

The functions for loading ARCS and BSB charts are contained in the respective function sets
EcArcs* or EcBSB*. Please refer to chapter ARCS or BSB for details.

50
 EC2007 ECDIS Kernel Programming Guide

Please note:
BSB support is only available for Windows 32bit.

6.5.15 Other Files

In addition to the different chart types and packages mentioned in the previous chapters
many types of referenced files are recognized and can be imported with the functions
EcDENCImportFile or EcDENCImportTree. Supported file types are TXT, HTM for text files or
TIF, BMP, JPG for picture files.

6.6 Chart Display

One of the most important features of the SevenCs EC2007 ECDIS Kernel is the chart display
on the screen.
Figure 2 depicts the structure and the different components of the visualization concept.
Figure 3 shows the main EC2007 ECDIS Kernel functions used for a standard chart display
system. The single components are described in the following chapters.

Figure 2: The Visualization Concept

The following three basic steps are necessary in order to display the SENC data.
1. Determination of charts which belong to the view (chart loading)
2. Determination of symbolization instructions for all objects (symbolization)
3. Drawing the chart image

51
EC2007 ECDIS Kernel Programming Guide

Although it is still distinguished between symbolization and drawing there is the function
EcDraw[NT|X11]DrawChart which checks automatically whether the symbolization process is
required or the chart image just needs to be drawn.
Figure 3 shows the individual steps which have to be performed for the chart display. The
steps and functions are described in the following chapters.

52
 EC2007 ECDIS Kernel Programming Guide

Figure 3 Main Visualization Steps

53
EC2007 ECDIS Kernel Programming Guide

6.6.1 View Structure

The view structure, in the following chapters simply called view, holds and manages all
information needed for creating the chart display. It is the most important part of the
visualization process. This view is created at the beginning of an application, and is deleted
at the end.
The view consists of the following main components:
• Display List: A list - created by the Display List Generator - of drawing
instructions for a cell
• Cell Entry: A data structure referencing the cell and containing the
respective Display List
• Cell List: Contains all Cell Entries needed for covering the current chart
display
• Cell Cache: Contains the Cell Entries that are no longer needed for the
current chart display
• Viewport: Defines the area on the earth's surface to be displayed on the
screen
• Mariners Settings: Option that influences the appearance of the chart display and
can be changed by the ECDIS user
• Presentation Library: Contains the information for the presentation of each object
class

The following EC2007 ECDIS Kernel components work with the view:
• Cell Loader A program module utilizing the cell catalogue for loading cells
that optimally cover the current viewport.
• Display List Generator: a program module that assigns the correct symbol
instruction to each object by evaluating the object
characteristics and the current display settings.
• Drawing Engine A program module that utilizes the Display Lists and
Presentation Library for generating the chart image.

6.6.2 View Handling

A view is represented by a structure of the type EcView. The definition of this structure is not
visible to the user. All functions using the view have a parameter serving as pointer to the
view structure.
Before calling one of these functions the view must be created and initialized with the
function EcChartViewCreate. This usually happens once at the start of the application. The
parameters are:

54
 EC2007 ECDIS Kernel Programming Guide

• dict A pointer to the dictionary structure as returned by the function

EcDictionaryReadModule (see chapter Dictionary Handling).
• resolution Information about the screen resolution
This implies that the dictionary must be read before a view is created, and should only be
released after the view has been deleted. It also should not be changed as long as the view
exists. The dictionary is needed in the view to correctly access the Lookup Tables, and to
avoid inconsistencies during the symbolization.
For the different screen resolutions we advise to use following values:
• EC_RESOLUTION_VERYHIGH for screen resolutions greater than or equal to 1920 ×
1080 pixels.
• EC_RESOLUTION_HIGH for screen resolutions greater than or equal to 1280 x
1024 pixels.
• EC_RESOLUTION_MEDIUM for screen resolutions between 1280 x 1024 and 1024 x
768 pixels.
• EC_RESOLUTION_LOW for screen resolutions 800 x 600 pixels or less.
This parameter is needed to determine the appropriate set of raster symbols to be used. It
ensures that the raster symbols are displayed in the required size on any screen.

Please note:
If the projection buffer (see chapter Projection Buffer) is used for performance reasons it
is advisable to utilize one view for the official read-only chart database, stored in the
DENC structure, and one view for cells which are used for overlay purposes with
frequently changing objects, e.g. own ship, past track etc. (see chapter Chart Overlays).

If a view is no longer needed it should be deleted using the function EcChartViewDelete. This
function frees all resources managed by the view, and frees the memory allocated to the
view structure. The memory allocated to the dictionary structure is not freed by this
function. After deleting the view with EcChartViewDelete it cannot be passed on to any ECDIS
Kernel functions anymore.
The function EcChartViewCopy is used to copy information from one view to another. The
information is grouped into pick, symbolize, and draw information.

Please note:
The current ECDIS Kernel version only supports copying pick information. Using this
function is potentially dangerous. We strongly recommend setting the view parameters
with the standard functions.

All functions that use a view are able to write error messages into a special log file. This log
file can be passed to the view with the function EcChartSetErrorLog. With this function logging
of error messages can be turned off again, too. Initially the error log is turned off when
creating a view.

55
EC2007 ECDIS Kernel Programming Guide

6.6.3 The Viewport

The viewport defines the area on the earth’s surface to be displayed on the screen. It is
defined by a geographic position as its center, a range in nautical miles, and a rotation angle.
The range parameter is taken from the range of a Radar PPI and allows the ECDIS chart
display to appear in a similar scale as the Radar display for the purpose of easy comparison.
If, for example, the range is set to 6 nautical miles the ECDIS will display the chart from the
lower to the upper edge of the screen with an extension that covers about 12 NM
(depending on the selected projection). The range is also used to calculate the scale of the
electronic chart at the center of the viewport. Zooming is achieved by changing the range.
Using the settings of the viewport the cartesian coordinates are affinely transformed into
device coordinates. These device coordinates are used for drawing the chart. During this the
image is clipped to the size of the destination pixmap.
The formula for the Affine transformation is:

This formula is important if a “user-defined” projection shall be used (see chapter User-
Defined Projections).
The viewport is set with the function EcDraw[NT|X11]DrawChart which is called at the end of
the chart display process (see chapter Drawing Function).

6.6.4 Chart Loading

After the charts have been imported into the application’s chart database (see chapter Chart
Installation) they have to be loaded into the view structure (see chapter View Structure).

[Link] General Description

One of the important features of an ECDIS is a continuous chart display while the user moves
the view area or changes the display scales by zooming in or out. The aim is to fill the entire
screen with chart data leaving no blank areas. In ECDIS applications this is realized with a
chart loading concept which is mainly based on the usage or navigational purpose of the
ENCs.
The S-57 standard classifies digital charts into six different types of usage, according to their
use. The usage of a chart depends on the scale of its source, and it is the responsibility of the
data producer to set the correct usage for each chart. The six types of usage are:
• Usage 1: Overview With most details; best detailed usage
• Usage 2: General
• Usage 3: Coastal
• Usage 4: Approach
• Usage 5: Harbor

56
 EC2007 ECDIS Kernel Programming Guide

• Usage 6: Berthing Least detailed usage

Most ECDIS user interfaces allow a selection of the chart display by range, not by chart
usage. This makes it necessary to define a relation between range or display scale and the
chart usage.
Like the traditional radar ranges, display ranges define the radius of a circular view around
the center of the screen. The diameter of the view covers the vertical extent of the
rectangular chart display.

Figure 4: Display Range

The display scale is calculated from the range. Depending on the used screen size ranges
result in different display scales.
The calculated display scale is usually an odd number, which is again normalized to fit into a
list of standard scales. The value from the list of standard scales that is equal or greater than
the calculated display scale is used as the normalized display scale. The ECDIS Kernel
provides functions to determine the scale from a given range, EcDrawRangeToScale.
Each usage is assigned to an interval of paper chart scales. Extensive tests of loading
concepts in ECDIS have shown that it is advisable to load a chart at a smaller display scale
than the assigned paper chart scale.
The function EcDrawScaleToUsage is used to determine the usage from a given scale as
described here. This function is called by the high level function EcDraw[X11|NT]DrawChart
but can be used independently in case of the manual chart loading (see chapter Manual Chart
Display).
The relation between scale and usage is based on internal lists which can be extended by an
user defined list using EcDrawScaleToUsageExt. This function can only be used in case of the
manual chart loading.
The following table shows the different scale tables which can be defined.

SevenCs Table UKHO Table User defined Table Usage

> 3.000.000 > 300.000 ownTable[0] Overview
> 1.500.000 > 150.000 ownTable[1] General
> 350.000 > 50.000 ownTable[2] Coastal
> 120.000 > 20.000 ownTable[3] Approach
> 30.000 > 5.000 ownTable[4] Harbour

57
EC2007 ECDIS Kernel Programming Guide

<= 30.000 <= 5.000 ownTable[5] Berthing

Table 1: Scale to Usage Assignments

For instance in case of the UKHO table a coastal ENC will be loaded only at a scale bigger
than 1:50.000, i.e. you have to zoom in much further than with the SevenCs table. On the
other hand this approach provides a better performance, because ENCs with more details
will be loaded later.

Please note:
The returned usage values do not correspond to the S-57 usages 1 to 6 but to the SENC
usages EC_OVERVIEW etc.

The following table shows the relation of a range to the scale and the usage. The calculated
scale is based on a pix map size of 1280 x 800 and a 22” screen (470 x 294 mm).

Range Display Scale Usage Range Display Scale Usage

1000 17,800,000 Overview 6 107,000 Approach
500 8,900,000 Overview 4 71,000 Harbor
200 3,560,000 Overview 3 53,000 Harbor
100 1,781,000 General 2 36,000 Harbor
48 855,000 Coastal 1.5 27,000 Berthing
32 570,000 Coastal 1 18,000 Berthing
24 427,000 Coastal 0.75 13,000 Berthing
18 320,000 Approach 0.5 8,900 Berthing
12 214,000 Approach 0.25 4,500 Berthing
8 142,000 Approach 0.1 1,800 Berthing
Table 2 Range – Scale – Usage

The chart loading concept takes a selected range, calculates the corresponding display scale
(e.g. 1:570,000), and then determines the appropriate usage (e.g. Coastal) to be loaded.
With this usage the cells which cover the chart view can be identified. The corner
coordinates of the chart view are calculated from the centre of the view, its vertical and
horizontal extent, and the standard display scale. The result is an area of the earth's surface
which is to be displayed on the screen.
The chart catalogue of the ECDIS software contains copies of the coverage objects of all
available cells. From this catalogue the cells are selected that partially or completely cover
the area, and are of usage equal to or less detailed than the determined usage.
The names of the selected cells are included in a preliminary list of charts to be displayed.
This list contains charts of various usage types but not of usage more detailed than the
determined usage.

58
 EC2007 ECDIS Kernel Programming Guide

From this preliminary list the cells to be loaded are determined. The selection is realized by
first placing a virtual web, i.e. a grid, on the chart window of the earth's surface. At each
intersection point of this grid the chart with the best usage covering that geographical
position is selected from the preliminary list. All charts in the resulting list are loaded into
memory from which they can be drawn on the ECDIS screen.
The following picture shows an example of a preliminary chart list and the selection of the
charts that are actually loaded into memory.

Figure 5: Chart Selection from Preliminary List of Charts

The usage that has been determined from the selected range is Harbor. Therefore cells of
usage Berthing are not included in the preliminary list. When stepping through the
intersection points of the grid, chart A of usage General will never be selected because there
is always a chart of a more detailed usage covering the geographical position. Chart E of
usage Coastal will not be included in the list either since chart F of usage Approach covers its
entire area. As a result the charts B, C, D, F, and G will be loaded into memory.

[Link] Chart Loading Function

The chart loading function Ec[DENC|Chart]LoadViewByAreaExt is included in the function
EcDraw[NT|X11]DrawChart which is called at the end of the chart display process (see chapter
[Link]).

[Link] Cell List and Cache

Inside the view there are two containers to hold the Cell Entries: the Cell List and the Cell
Cache (see also Figure 2). The Cell List contains the Cell Entries momentarily needed to create
the chart display while the Cell Cache contains Cell Entries no longer required for the current
chart display. The latter Cell Entries are kept inside the Cell Cache in case they might be
needed for a subsequent chart display. This has the advantage that these cells need not be
symbolized again because their Display Lists are still available. These two containers are
disjoint, which means that the Cell Entry of a particular cell cannot be located in both
containers at the same time.
After having selected the list of cells to be loaded into memory as described in the previous
chapter the following steps are taken for each cell in this list:
• It is checked whether a Cell Entry for the cell already exists within the Cell List. If so, the
cell has already been needed for the creation of the previous chart display. The Cell Entry
will stay in the Cell List. If not …
• it is checked whether a Cell Entry for the cell is located in the Cell Cache. If so, this entry is

59
EC2007 ECDIS Kernel Programming Guide

moved from the Cell Cache to the Cell List, including the Display List, so this cell will not
have to be symbolized again. If not …
• a new Cell Entry is created in the Cell List. The Display List of this entry is still empty since
the cell has not yet been symbolized. The creation of such Cell Entry also includes the
mapping of the corresponding cell.
• In the end all Cell Entries in the Cell List that are not needed for the current chart display
will be moved to the Cell Cache.
In contrast to the Cell List the Cell Cache has a limited capacity. When the Cell Cache limits
have been reached the oldest Cell Entry will be removed from the Cell Cache. This also
results in the corresponding cell being unmapped.
If one of the parameters that influence the symbolization, e.g. the mariner’s settings (see
chapter 7.1.6), is changed the Display Lists of all cells will become invalid, even those kept in
the Cell Cache. The purpose of the Cell Cache is to store the Display Lists of cells in order to
reuse them in a later chart display. In case all Display Lists are invalid the Cell Cache will be
completely emptied.
To take advantage of the Cell Cache the function EcChartSymbolizeView must be used (see
chapter Symbolization Function).
The function EcChartUnloadView also empties the Cell Cache just like the function
EcChartFlushCellCache.
The following example shows the functions that must be called to take advantage of the Cell
Cache. It shows a sub-function to draw a chart for the operating system UNIX (X-Window
specific function calls).

[Link] Cell Order

When a chart is drawn it is usually made up of several cells from different usages. In this case
cells are sorted by their usage. These usages act as layers. The less detailed cells (usage
"Overview") are drawn first, then followed by the more detailed ones (usage "Berthing"). In
this way the most detailed cells are drawn on top of all others. Within a usage, the cells are
sorted by their official/non-official status. The producer agency code of a cell is used to
determine whether the data are official or non-official. The non-official cells are drawn first,
then followed by the official ones. In this way the official cells are drawn on top of the non-
official cells, covering them where they overlap. This ensures that official data are always
displayed on top of non-official data (within the same usage). You can change this behavior
by using the function EcDrawSetCellSortOrder.
To find out the current sort order of official/non-official cells you can use the function
EcDrawGetCellSortOrder.

6.6.5 Chart Symbolization

Before charts can be drawn it must be determined how each single object has to be drawn.
This depends on the symbol instructions of the Presentation Library (please refer to the
document EC2007_BackgroundInformation for details), but is also influenced by the chart
display settings. All these parameters are stored in the so-called display list and handled by
the display list generator. Both are described in the following chapters.

60
 EC2007 ECDIS Kernel Programming Guide

[Link] Chart Display Settings

There are many parameters with which the chart display can be configured. Most of these
parameters belong to the so-called mariner’s settings (see chapter 7.1.6). In addition there
are some other general chart settings which can be defined by the user (see chapter Other
Chart Display Settings).

[Link] Display List

To understand the automatic chart loading concept described above it is important to know
how cells are managed in the view structure. Each cell is combined with its Display List to
form a Cell Entry. During the symbolization process the Display List is created for all loaded
cells. It contains simple drawing instructions like line, symbol, area, and text drawing
instructions but no coordinates. Instead of containing the coordinates a reference to the
corresponding spatial objects holding the geographic coordinates is stored in the Display List.
The transformation into the corresponding screen coordinates is performed during the
succeeding drawing process which represents working off the Display List. The Display List is
sorted by the drawing sequence thus enabling a simple linear procedure. The biggest
advantage of this concept is the reuse of the Display List in case only the viewport has
changed. This change only results in a new transformation of the geographic coordinates. A
generalization when changing the scale is also possible without renewing the Display List
because the minimum and maximum display scale of each drawing instruction is included in
the Display List.
The symbolization depends on various parameters, which means that changing these
parameters will result in the necessity to rebuild the Display List. All these parameters are
managed in the view structure, too.
The sort order of the display entries in the output array is as follows:
1. Entries for area, line and point instructions sorted by their display priority (lowest first).
2. Entries for text instructions sorted by their display priority (highest first).
In case the internal drawing functions (GDI for Windows, X11 for Linux) shall be replaced by
user-defined drawing functions the display list can be directly accessed by the functions
EcDrawGetDisplayListEntries or EcDrawGetCellDisplayListEntries respectively in order to query
the internal drawing functions. These functions allocate memory to the array of display list
entries. This memory must be freed by calling EcDrawReleaseDisplayListEntries.

Please note:
Changing the drawing functions is a significant intervention in the internal functionality
of the EC2007 ECDIS Kernel and should be performed very carefully and only if it is
definitely necessary.

[Link] Display List Generator

The elements of the Presentation Library (see document EC2007_BackgroundInformation) are
handled by the so-called 'Display List Generator' of the ECDIS Kernel. This piece of code
creates the link between the object characteristic according to S-57, and the actual
presentation on the ECDIS screen according to S-52. Figure 6 shows how the various
elements of the Presentation Library are linked together to display an S-57 object from the

61
EC2007 ECDIS Kernel Programming Guide

SENC. The individual elements (symbol library, lookup tables, etc.) are part of the
Presentation Library.
Basically the Display List Generator is a program loop that retrieves objects one by one from
a cell database. Since the cell does not contain information about the color of its objects or
which symbol is to be used the symbolization must be derived from the object description.
Thus the object's attribute values are used to search for the appropriate symbolization
instruction within the lookup tables. In some cases the instruction found in the lookup table
is a call to a conditional symbolization procedure. These procedures contain a decision
process that interprets the object's attributes and geometry to generate symbolization
instructions.
At this point symbolization instructions for the display of the objects are available regardless
of whether they came directly from the lookup table or were generated by a symbolization
procedure. These symbolization instructions are then interpreted and converted into a set of
system specific graphic commands that are stored in a Display List.

Figure 6: Generation of Display List

62
 EC2007 ECDIS Kernel Programming Guide

Each graphic command in the Display List is assigned to the display priority that has also
been previously retrieved from the lookup table. The display priorities are defined according
to the requirements of the IMO and IHO.
After all objects have been examined by the program loop the Display List is filled with
graphic commands. These commands are then performed by the ECDIS graphics engine
which in turn loads symbols from the symbol library, and gets the color values from the color
tables.
This concept for generating a chart display gives the ECDIS user, or mariner, full control over
the content and the appearance of the presentation:
• if he selects e.g. another safety contour, the Display List will be renewed in the
programmed loop, and the blue shades of DEPARE (depth area) objects will be changed by
a symbolization procedure depending on the value of minimum depth; or
• symbolization instructions which refer to the traditional symbol set will be replaced by
instructions which refer to the simplified symbol set by switching to another lookup table;
or
• the generation of the Display List will be influenced by a filter suppressing text commands;
or
• the color values for the daytime will be replaced with those for the night time by selecting
another color table.

[Link] Symbolization Function

After the display list has been generated the cells of the view have to be symbolized before
they can be drawn. The symbolization is included in the function EcDraw[NT|X11]DrawChart
which is called at the end of the chart display process (see chapter Drawing Function).

6.6.6 Chart Projection

All geographic positions in an S-57 chart are given in un-projected geographic coordinates,
i.e. in latitude and longitude, based on WGS-84. For the display of the charts on a plane, e.g.
a screen, they must be projected. The projection consists of several steps, which are
illustrated in the next figure.

63
EC2007 ECDIS Kernel Programming Guide

Figure 7: Chart Projection Concept

[Link] Chart Datum

Charts conform to S-57 require all geographical positions (latitude, longitude) to be given in
WGS-84 datum. Therefore, the EC2007 ECDIS Kernel assumes by default that all given
positions are in WGS-84; i.e. every navigational calculation and projection initially works on
WGS84. Nevertheless, if geographic chart data are given in a local datum other than WGS84,
the datum can be set using the Kernel function EcDrawSetDatum. If a local datum is set with
this function all calculations will be performed on this local datum. The ECDIS Kernel includes

64
 EC2007 ECDIS Kernel Programming Guide

several predefined datums, or the local datum is defined by fixed shift values to WGS84
datum.
If a local datum has been set and it is no longer needed EcDrawSetDatum must be called to
reset to WGS84. The reset is not done automatically.
If the application reads from the database or writes to it the positions must be given in
WGS84. Therefore the functions EcDrawShiftFromWGS84 and EcDrawShiftToWGS84 must be
applied whenever a different local datum is used.
If an ARCS chart is loaded, the datum and projection has to be set to
EC_GEO_PROJECTION_ARCS. This adjusts the local datum to the datum of the ARCS chart.
It is also possibleto use your own datum transformations. The function
EcDrawSetDatumFunctions sets external conversion functions to be used for the datum
transformation within the Kernel.
The functions EcDrawXyToLatLon and EcDrawLatLonToXy are provided to transform positions
into device coordinates. They operate on the local datum and depend on the projection and
the viewport parameters. Note that a pixel position on the screen is given in rows (y-axis)
and columns (x-axis), with the origin of the coordinate system in the upper left corner of the
screen.

[Link] Projection Types

The most famous projection for nautical purposes is the Mercator projection because of its
ability to represent lines of constant course, known as rhumblines or loxodromes, as straight
segments.
The EC2007 ECDIS Kernel supports the following projections:

Cylindrical Projections

Cylindrical Equidistant Projection („No Projection“)

A projection in which the surface of the earth is conceived as developed on a tangent
cylinder, which is then spread out to form a plane. It has uniform spacing of the parallels and
meridians.

Spheroidal Mercator Projection

A cylindrical projection with a cylinder tangent along the equator, meridians appear as
equally spaced vertical lines and parallels as horizontal lines drawn farther apart as the
latitude increases, such that the correct relationship between latitude and longitude scales
at any point is maintained.

Equirectangular Cylindrical Projection (Plotting Sheet Projection)

Similar to Spheroidal Mercator projection, but less accurate for small scales.

Transvers Mercator Projection

In principle equivalent to the regular Mercator Projection turned 90° in azimuth.

Conform Gauß-Krüger Projection

System based on Transvers Mercator Projection using belts 4° in width where the center
longitudes are 3° apart. The numbers of the belts are derived from the degrees of the center
longitude divided by 3 (6°->2, 9°->3, etc.). The Bessel Spheroid is used as the figure of
reference. This system is mainly used in Germany.

65
EC2007 ECDIS Kernel Programming Guide

Universal Transvers Mercator Projection

System also based on Transvers Mercator Projection using belts 6° in width starting from the
meridian 180° east or west of Greenwich. The belts are numbered 1 to 60, west to east.
These belts are called zones. A scale factor of k0=0.9996 is used on the center longitude of
each zone. The International Spheroid is used as the figure of reference.

Zenithal Projections

Oblique Zenithal Equidistant Projection (Radar Projection)

Projection on which straight lines radiating from the center represent great circles in their
true azimuth from that center, and lengths along those lines are of exact scale.

Oblique Zenithal Orthographic Projection (Globe Projection)

Perspective projection in which the projecting lines, emanating from a point at infinity, are
perpendicular to a tangent plane.

Oblique Zenithal Gnomonic Projection

Perspective projection in which the projecting lines emanate from a point at the center of
the earth. Great circles appear as straight lines.

Oblique Zenithal Stereographic Projection

Perspective projection in which the projecting lines emanate from the antipode.

Polar Zenithal Stereographic Projection

Polar case of the Stereographic Projection, i.e. the projection axis coincides with the polar
axis of the earth. In contrary to the Stereographic Projection mentioned above, this
projection is calculated on the spheroidal earth.

Conic Projections

Lambert Conformal Projection

Conic projection with two standard parallels (secant conic projection), in which the spacing
of the parallels is altered, such that the distortion is the same along them as along the
meridians, making the projection conformal.

Polyconic Projection
Secant conic projection in which the latitude limitations have been minimized by using a
series of cones. Each parallel is the base of a tangent cone. At the edge of the chart, the area
between the parallels is expanded to eliminate gaps.

Raster Chart Projections

Each ARCS and BSB chart comes with its own particular projection (e.g. Mercator or UTM); a
polynomial geo-referencing algorithm and a chart specific parameter set are used to convert
pixel units into geographical coordinates of the chart’s local datum (ARCS).

[Link] Projection Definition

The behavior of a projection depends on projection parameters. These parameters are
specified by the function EcDrawSetProjection. They are described in the following table.

66
 EC2007 ECDIS Kernel Programming Guide

EC_GEO_PROJECTION_… P1 P2 P3 P4
…_NONE n/a center longitude n/a n/a
…_GK n/a center longitude n/a n/a
…_UTM* center latitude center longitude n/a n/a
…_UTM_EXT center latitude center longitude Zone n/a
…_CYLINDRIC latitude of true center longitude n/a n/a
scale
…_MERCATOR latitude of true center longitude n/a n/a
scale
…_PSEUDOMERCATOR n/a center longitude n/a n/a
…_RADAR latitude of longitude of n/a n/a
tangency tangency
…_ORTHOGRAPHIC latitude of longitude of n/a n/a
tangency tangency
…_ARCS n/a n/a n/a n/a
…_ARCS_EXT n/a n/a n/a n/a
…_TRANSVERS_ scaling factor center longitude n/a n/a
MERCATOR
…_TRANSVERS_ center latitude center longitude scaling n/a
MERCATOR_EXT factor
…_POLAR_ latitude of true center longitude n/a n/a
STEREOGRAPHIC scale
…_POLAR_ latitude of true center longitude scaling variant id
STEREOGRAPHIC_EXT scale factor
…_STEREOGRAPHIC latitude of longitude of n/a n/a
tangency tangency
…_GNOMONIC latitude of longitude of n/a n/a
tangency tangency
…_POLYCONIC center latitude center longitude n/a n/a
…_LAMBERT_ center latitude center longitude standard standard
CONFORMAL_CONIC parallel parallel
farther nearer to
from the the
equator equator
…_SCHREIBER center latitude center longitude scaling n/a
factor
…_PLATTE_CARREE minimum minimum n/a n/a
latitude longitude

67
EC2007 ECDIS Kernel Programming Guide

* The projection EC_GEO_PROJECTION_UTM uses the spheroid EC_SPHEROID_INT

regardless which datum has been set. EC_GEO_PROJECTION_UTM_EXT uses the spheroid of
the configured datum
Some of the projections are restricted to a geographic range (e.g. the Mercator projection is
not defined at the poles), and in the speed of the calculations:

Projection Range of geographic position Speed

NONE 90°S to 90°N, 180°W to 180°E fast
MERCATOR, PSEUDO 80°S to 80°N, 180°W to 180°E medium
MERCATOR
CYLINDRIC 80°S to 80°N, 180°W to 180°E fast
TRANSVERS_MERCATOR 90°S to 90°N, center longitude +/- medium
90°
TRANSVERS_MERCATOR_EXT 90°S to 90°N, center longitude +/- slow
90°
GK 90°S to 90°N, center longitude +/-3° medium
UTM 90°S to 90°N, center longitude +/-6° medium
UTM_EXT 90°S to 90°N, center longitude +/-6° medium
RADAR 90°S to 90°N, center longitude +/- slow
180°
ORTHOGRAPHIC 90°S to 90°N, 180°W to 180°E slow
STEREOGRAPHIC 90°S to 90°N, 180°W to 180°E slow
POLAR_STEREOGRAPHIC 90°S to 90°N, 180°W to 180°E slow
POLAR_STEREOGRAPHIC_EXT 90°S to 90°N, 180°W to 180°E slow
GNOMONIC 90°S to 90°N, 180°W to 180°E slow
ARCS only in the area of the ARCS chart medium
POLYCONIC 90°S to 90°N, 180°W to 180°E slow
LAMBERT_CONFORMAL_CONIC 90°S to 90°N, 180°W to 180°E slow

The spheroidal Mercator projection is commonly used for ECDIS displays because it is the
projection of the nautical paper charts. For ranges less than about 12 NM in high latitudes
and up to 50 NM at the equator the cylindrical projection is a fast alternative with no visible
distortions. Nevertheless both projections are limited in their use in higher latitudes. In such
cases the projection should be switched to a zenithal projection; recommended is the polar
stereographic projection.
For large ranges SevenCs recommends the gnomonic projection because great circles appear
as straight lines

68
 EC2007 ECDIS Kernel Programming Guide

To check if the defined projection is reasonable the function EcDrawAdviseProjection can be

used. The function returns a projection which is advised according to the given parameters
range and center latitude. If the currently defined projection is reasonable or valid the
function returns EC_GEO_PROJECTION_NONE. If the range is bigger than 200nm it returns
EC_GEO_PROJECTION_GNOMONIC. If not, it checks if the upper latitude of the viewport is
bigger than 70°. In that case it returns EC_GEO_PROJECTION_POLAR_STEREOGRAPHIC_EXT.
In all other cases it returns EC_GEO_PROJECTION_MERCATOR.

[Link] Projection Buffer

When drawing a chart image the geographical latitude/longitude coordinates of an ENC data
set must be converted into screen coordinates by applying the selected projection
algorithms. The Kernel maintains a buffer for these projected coordinates. The function
EcDrawSetProjectionBuffer is used to control the usage of this buffer. If it is enabled the
Kernel will store the results of projection calculations for node and edge coordinates in this
buffer. These results can then be re-used in subsequent projection calculations.
This procedure saves a lot of CPU cycles, and the chart picture will be drawn much faster.
However, there are some potential risks, too:
If the contents of a cell are edited while the buffer is enabled, e.g. a node is moved to a
different location, these changes will not be displayed correctly because the projection
buffer still holds the old coordinates.

Please note:
When a cell is going to be edited the buffer should be disabled.

A good example is a cell which contains the past track of a ship. Whenever the ship moves a
position is added to the past track. In that case, the projection buffer should not be enabled
for the view the cell concerned is assigned to.
To find out the status of the projection buffer in a specified view you can use the function
ECDrawGetProjectionBuffer.

Please note:
If the projection buffer is used it is advisable to have one view for the official read-only
chart database, stored in the DENC structure, and one view for cells which are used for
overlay purposes with frequently changing objects, e.g. own ship, past track etc (see
chapter 7.2.1 Overlay Cells).

6.6.7 Chart Drawing

The chart picture is the result of interpreting the Display List of one or more cells, and
executing the simple drawing commands it contains. In most cases the drawing destination
is a pixmap (an invisible, rectangular area located in the computer's memory), which is
copied into a window after the completion of the drawing process.

69
EC2007 ECDIS Kernel Programming Guide

Please note:
If a window is specified as drawing destination an incomplete chart picture will be shown
before the drawing process is terminated. This should be strictly avoided.

[Link] Color Handling

The colors which are used for the display of charts are defined in the S-52 Presentation
Library (see document EC2007_BackgroundInformation).
The color definitions are stored in a file called [Link]. It is located in the directory
$LIB_7CS/lib/preslib4/color. Each color entry in this file contains the color token, the CIE
coordinates, and the RGB values.
In the symbolization instructions of the Presentation Library colors are referenced by their
tokens. In most computer graphic systems colors are identified by an index in a palette. The
ECDIS Kernel uses graphic library functions for drawing charts (X11 on UNIX systems, GDI on
Windows systems). This implies that symbolization instructions have to be translated into
drawing functions.
Before any charts can be symbolized or drawn with ECDIS Kernel functions all color
definitions must be read. The function EcChartReadColors reads the specified file and stores
the color tokens and the corresponding RGB values in the view structure.
The parameters are:
• view Pointer to a view structure
• name Name of the color file to be read
This function returns the number of color definitions read from the specified file. If an error
occurred, the function returns 0. If the color file is not specified (parameter name is NULL)
the function tries to read the default file [Link] (see above).
For a given color scheme the RGB color definitions of a color token can be obtained as stored
in the view after reading all colors. The function EcDrawGetColorDefinition is used to retrieve
the RGB definition and the color token if the logical index is known. The function
EcDrawGetTokenRGB is used to retrieve the RGB definition if the color token is known. The
function EcChartGetColorByName is used to retrieve the logical color index if the color token
is known.
The internal index table stored in the view structure assigns a logical color index to a system
palette index. Per default the color tokens are indexed in the order they appear in the color
definition file. If this internal color index table is not changed the logical color index is
identical with the system palette index, so the value returned by the function
EcChartGetColorByName can be used in a system palette. If, however, the internal color index
table has been modified the logical color index must be converted into the correct system
palette index. This can be done with the function EcGetColorIndex.
The function EcDrawSetColorIndex must initially be used to assign a new system index to a
given logical index and can be used to modify the internal index table.
EcChartAddColor adds a new color token to the list of pre-defined tokens,
EcChartGetNumberOfColors returns the number of defined tokens.

70
 EC2007 ECDIS Kernel Programming Guide

The number of pre-defined tokens is 67. This may affect programs which create a palette of
64 chart colors and 3 overlay planes using a total of 256 colors.
The ECDIS Kernel also provides a convenient function for setting a system palette, the
function EcDraw[X11|NT]SetColorScheme. However, this function is not very flexible. Usually
the application will create and set a system palette itself in order to have full control over
the palette indices used for the user interface, and other graphic elements which are not
part of the chart display.

Windows Users please note:

In very few cases the "no data" color might be drawn as black instead of grey-green as
required by the S-52 standard. This can be corrected by changing a function call from
EcDrawNTSetColorScheme to EcDrawNTSetColorSchemeExt with the last parameter offset
set to 1.

The procedure of creating and setting a system color palette includes:

• Reading the color definition file with EcChartReadColors.
• Initializing the drawing routines of the ECDIS Kernel with EcDraw[X11|NT]Initialize.
• Creating a color palette using the functions specific to the respective operating system,
e.g. CreatePalette under Windows or XCreateColormap under X11. For Windows the
function EcDrawNTSetColorScheme can also be used to create the color palette.
• Setting the palette’s RGB values to the RGB values of the color definitions stored in the
view structure. These values can be retrieved with EcDrawGetColorDefinition.
• Activating the system color palette by selecting it into the device context (Windows) or
installing the colormap (X11).
All these steps are mandatory and usually performed once at the start of the application.

[Link] View Draw Initialization

Before any drawing function can be called they must be initialized with the function
EcDraw[NT|X11]Initialize. This must happen once at the start of the application and whenever
the window or screen size has been changed.
The function takes the following parameters:
• view Pointer to view structure
• [dc|display] Used only for LINUX, display to be used for drawing
• Size_X Horizontal size of the created pixmaps (pixel)
• Size_Y Vertical size of the created pixmaps (pixel)
• ScreenWidth Horizontal size of the used CRT (mm)
• ScreenHeight Vertical size of the used CRT (mm)
• makeBitmaps Create private bitmaps and DC / GC (yes/no)
If makeBitmaps is set to True it will create a graphics context and two bitmaps for double
buffered drawing of charts. These resources can be requested with EcDrawNTGetResources
and freed by using EcDrawEnd. If makeBitmaps is set to False, bitmap and DC / GC have to be
created by the application. The parameters ScreenWidth and ScreenHeight influence

71
EC2007 ECDIS Kernel Programming Guide

range/scale calculations and the size and aspect ratio of vector symbols. They may be set to
0, in which case the size of the CRT is read from the file [Link] in $LIB_7CS/lib/config.
EcDraw[X11|NT]Initialize also calculates the aspect ratio and pixel size of the screen, which
are used in turn by EcDrawSetViewport to calculate the correct display scale and symbol size.

[Link] Drawing Settings

Besides the settings for the projection, colors and screen/window size there are other
parameters which influence the drawing of the chart image. They are all optional and
described in chapter 7.1.8.

[Link] Drawing Function

The final drawing function is included in the function EcDraw[NT|X11]DrawChart. Besides the
drawing of the chart this function also loads the needed cells into the view and symbolizes
the view. The function takes following parameters:
• view pointer to a view context, previously created with EcChartViewCreate.
• dc The device context to draw with
• pixmap Not used, may be NULL
• dictInfo Not used, may be NULL
• catList Pointer to a cell catalogue list
• centerLat Latitude of chart center
• centerLon Longitude of chart center
• range Range of chart (like radar range) in nautical miles
• heading Rotation of chart in nautical degrees
During the interpretation of the Display List several filters are applied in order to make the
chart picture more legible. The first filter checks the actual display scale which is compared
with the attribute ‘SCAMIN’, which may be given for every object in the SENC file. An entry
for this attribute exists in the display list. If the value of the actual scale is larger than the
object's ‘SCAMIN’ value the display list entry for that object will not be executed. Here is an
example:
A ‘tower’ object has the ‘SCAMIN’ attribute value set to 50,000, the actual chart scale is
1:100,000. Thus the tower will not be drawn. With a chart scale of 1:30000 the tower would
be drawn. The chart scale can be obtained by calling EcDrawGetChartScale, and converted
into the corresponding range by EcDrawScaleToRange (and vice versa by
EcDrawRangeToScale).
The second filter prevents text information from overwriting each other. Lines and areas are
clipped so that only their visible parts are drawn. Point symbols are shown only if their
geographic position is located within the screen. Whenever a point symbol is drawn its
bounding box on the screen is stored in the view. These bounding boxes are used by
EcQueryPickVisible and allow to query information about point objects without hitting their
exact position.

72
 EC2007 ECDIS Kernel Programming Guide

[Link] Tiling
The Kernel does not provide any tiling mechanism. If you want to tile the images delivered
by the Kernel you should first let the Kernel create the complete image and then tile the
image yourself. If you let the Kernel create every single tile in the resulting image there
might be mismatching texts or several "centered" symbols for one area.

6.6.8 Callbacks
To keep the process of visualization as flexible as possible callbacks can be defined by the
user. Callbacks are added with the function EcChartAddCallback. The definition of this
function is
void EcChartAddCallback(EcView * view,
EcViewCallbackType callbackType,
EcViewCallbackProc callbackProc,
caddr_t userData)

Values which can be used for callbackType:

Type Annotations
EC_PRE_SYMBOLIZE_VIEW_CALLBACK All callbacks in this list will be called before the
complete view is symbolized.
EC_PRE_SYMBOLIZE_CELL_CALLBACK All callbacks in this list will be called before
every single cell in the view is symbolized.
EC_POST_SYMBOLIZE_CELL_CALLBACK All callbacks in this list will be called after every
single cell in the view has been symbolized.
EC_POST_SYMBOLIZE_VIEW_CALLBACK All callbacks in this list will be called after the
complete view has been symbolized.
EC_PRE_DRAW_VIEW_CALLBACK All callbacks in this list will be called before the
complete view is drawn.
EC_PRE_DRAW_USAGE_CALLBACK All callbacks in this list will be called before
every single usage of the view is drawn.
EC_POST_DRAW_USAGE_CALLBACK All callbacks in this list will be called after every
single usage of the view has been drawn.
EC_PRE_DRAW_OVERLAY_CALLBACK All callbacks in this list will be called before the
overlay is drawn.
EC_POST_DRAW_VIEW_CALLBACK All callbacks in this list will be called after the
complete view has been drawn.

The prototype for callback functions is defined as follows:

typedef void(*EcViewCallbackProc)(EcView *view,
const EcViewCallbackStruct *cbs,
caddr_t userData);

73
EC2007 ECDIS Kernel Programming Guide

The first parameter is the view the callback function has been logged in for; the second
parameter is a pointer to a structure which is transferred from the EC2007 ECDIS Kernel to
the function.
The third parameter is a pointer to user-defined data of the function EcChartAddCallback.
The structure of EcViewCallbackStruct is like this:
typedef struct _EcViewCallbackStruct
{
EcViewCallbackType reason;
EcCellId cellId;
UINT32 usage;
HDC dc; //(NT only)
Display *display; //(Unix only)
Drawable drawable; //(Unix only)
GC gc; //(Unix only)
} EcViewCallbackStruct;

The parameters are:

• reason Contains the callback type.
• cellId Contains a cell identifier. Only used in case reason is
EC_PRE_SYMBOLIZE_CELL_CALLBACK or
EC_POST_SYMBOLIZE_CELL_CALLBACK
• usage Contains the intended usage if reason is EC_PRE_DRAW_USAGE_CALLBACK
or EC_POST_DRAW_USAGE_CALLBACK
• dc The device context to draw with. Only used in case reason is
EC_XXX_DRAW…. Should only be changed locally (Windows only).
• Display The display to draw into. Only used in case reason is EC_XXX_DRAW… (Unix
only).
• drawable The drawable to draw into. Only used in case reason is EC_XXX_DRAW….
(Unix only).
• gc The graphics context to draw with. Only used in case reason is
EC_XXX_DRAW…. Should only be changed locally (Unix only).

To remove a callback you can use the function EcChartRemoveCallback.

To remove all callbacks of one type use the function EcChartRemoveAllCallbacks.

74
 EC2007 ECDIS Kernel Programming Guide

7 Specific ECDIS Functionality

7.1 Chart Display and Mariner’s Settings

7.1.1 Display Categories

In the IEC 61174 Standard three different level of the display of chart information are
defined, the so-called display categories, i.e. Display Base, Standard and Other. In addition
IEC62388 defines another one for Chart Radar application, i.e. the Primary chart information
set (PCIS). For details please refer to the EC2007_BackgroundInformation document.
The implementation of the display categories is done in the S-52 lookup tables. For each
entry a display category or viewing group is defined.
The display categories are switched to on or off with the function EcChartSetViewClass which
switches the viewing groups of a particular view class on/off. Possible values for the viewing
class are EC_DISPLAYBASE, EC_STANDARD, EC_OTHER or EC_PCIS.
EcChartGetViewClass returns the current view class.
As a precaution the function EcChartSetViewClass internally sets DISPLAYBASE to on if
STANDARD is switched on, and sets both DISPLAYBASE and STANDARD to on if OTHER is
switched on. This functionality ensures that applications are programmed according to the
IMO specifications.

Please note:
EcChartSetDisplaySelector, EcChartSetShow* and EcChartSetViewingGroup (see below)
overwrite the settings of EcChartSetViewClass. Therefore the user interface must display a
note to prevent the user or mariner from switching off viewing groups that are in the
display category DISPLAYBASE.

7.1.2 Display Selectors

With the new editions 4.0 of the IHO Presentation Library and the IEC 61174 Standard the
chart and mariner’s settings have been re-organized and renamed to display selectors. This
led to the introduction of the function EcChartSetDisplaySelector. However the former
functions EcChartSet* are still available but should not be used in conjunction with
EcChartSetDisplaySelector.

The display selector consists of a structure with following members:

Display selector structure member Low level function
Bool bShowQualityInformation EcChartSetShowQualityInformation
Bool bSetSymbolizationDateRange EcChartSetSymbolizationDateRange
unsigned long secondsStart, secondsEnd EcChartSetSymbolizationDateRange
Bool bHighlightDateDependendObjects EcChartSetShowDateDependencies

75
EC2007 ECDIS Kernel Programming Guide

Bool bShowInformPoints EcChartSetShowInformPoints

Bool bShowExtFiles EcChartSetShowExternalReferences
Bool bShowUnknownObjects EcChartSetShowSymbolFail
Bool bUseScamin EcChartSetUseScamin)
Bool bShowShallowPattern EcChartSetShowShallowPattern
Bool bShowShallowWaterDangers EcChartSetShowShallowWaterDangers
Bool bShowDepthContourLabels EcChartSetShowDepthContourLabels
EcChartSetShowSafetyContourLabels
Bool bShowTwoShades EcChartSetShowTwoShades
Bool bShowNationalLanguage EcChartMergeLookupTable
Bool bShowSimplifiedPoints; EcChartSetLookupTableExt
Bool bShowPlainBoundaries EcChartSetLookupTableExt
Bool bShowImportantText EcChartSetShowImportantText
Bool bShowOtherText EcChartSetShowOtherText
int iLightSectorMode EcChartSetLightSectorMode

Please note:
A call of the listed low-level functions will interfere with the display selector settings and
should therefore be avoided.
In case non-ENC chart products are handled as well, the non-ENC lookup tables must be
merged whenever some value of the display selector has been changed.

7.1.3 Chart Settings

Independent of the display selectors following chart settings can be defined by
EcChartSetShow* functions:
Soundings EcChartSetShowDeepSoundings,
EcChartSetShowShallowSoundings
Lights EcChartSetShowLightFeatures

Overscale pattern EcChartSetShowOverScale

Official/Unofficial ENC boundary indication EcChartSetShowOfficialBoundary

76
 EC2007 ECDIS Kernel Programming Guide

[Link] Lights
Light features like the light sectors of a lighthouse or the light flare of a buoy are generally
not shown on the ECDIS display.

Please note:
The display of light features should be switched off in case the display category is set to
display base (see chapter Display Categories).

There are three different ways to present light sectors. They can be defined by means with
the member iLightSectorMode of the display selector structure. The modes are:
• EC_LIGHTSECTOR_FIXED: sector legs are displayed in 25mm, the arcs with a radius
of 20mm
• EC_LIGHTSECTOR_FULL: sector legs are displayed in full length, the arcs with a
radius of 20mm
• EC_LIGHTSECTOR_VARIABLE: sector legs and arcs are displayed in relation to the value
of nominal range and the light radius factor
The default value is EC_LIGHTSECTOR_FIXED.
In case of a variable light sector mode the factor for the radius of the light sector arcs can be
set with the function EcChartSetLightRadiusFactor. The default value is 0.1.
To distinguish lights on floating structures from all-round lights on fixed structures by a light
teardrop symbol the function EcChartSetLightDistinction can be used.

[Link] Soundings
Soundings are measured water depths or spots which have been reduced to a vertical
datum.
According to the IMO performance standards the chart presentation on the display also
depends on the safety values that are set by the mariner. The safety depth influences the
presentation of soundings and obstructions. Soundings with depth values greater than the
safety depth are regarded as deep soundings, and soundings with values smaller than the
safety depth are regarded as shallow soundings.
The safety depth is set with the function EcChartSetSafetyDepth.
By default the soundings are only shown in the display category “All other information”
(view class EC_OTHER).

[Link] Depth Contours and Areas Display

Depth contours are lines of equal water depth. The setting of the emphasized depth
contours influences the presentation of depth areas. There are three emphasized different
depth contours:

Safety Contour
This contour defines which water areas have sufficient depth for safe navigation. It is
symbolized as a thick solid line. The safety contour also defines the boundary of shallow and
deep-water areas.

77
EC2007 ECDIS Kernel Programming Guide

Shallow Contour:
This contour is always located in the shallow water area defined by the safety contour. It
divides this area again into two areas that are each symbolized with a different color. The
value of shallow contour must be smaller than the one of safety contour.

Deep Contour:
This contour has the same function as the shallow contour except for the deep-water area.
The value of the deep contour must be greater than the value of safety contour.
When setting these values it is recommended to keep the following relation:
Shallow < Safety < Deep contour, otherwise the chart image may have a strange appearance.
The following functions were designed to handle the display of depth contours and areas:
EcChartSetSafetyContour sets the value for the safety contour; EcChartGetSafetyContour
returns the value of the safety contour.
For non-ECDIS applications it might be required to change the appearance of the safety
contour with the function EcChartSetSafetyContourOptions. With it the parameters scale
minimum, over radar flag, line width and the line color can be set.
EcChartSetShallowContour sets the value for the shallow contour; EcChartGetShallowContour
returns the value of the shallow contour.
EcChartSetDeepContour sets the value for the deep contour; EcChartGetDeepContour returns
the value of the deep contour.
The three depth contours described above separate the complete water area into four areas
of different depth ranges, which are displayed in four different color shades. However, the
most important differentiation lies in the shallow and deep water areas, which is why it is
also possible to display the entire water area in only two color shades, one for the shallow
and one for the deep water area.
The following figure shows how the display of the depth areas is influenced by the different
contour values.

Figure 8: Display of Depth Areas

78
 EC2007 ECDIS Kernel Programming Guide

For non-ECDIS applications it is also possible to display depth areas with shades of grey. This
has to be defined during the color initialization with the function
EcDraw[NT|X11]SetColorScheme and its parameter greyFlag.

[Link] Overscale Indication

Each cell has a defined compilation scale depending on the resolution of the source data.
The compilation scale indicates the largest scale allowed to display the chart in order to use
it for navigation. It is the optimum scale at which data are displayed completely and all
information is legible. The value of the compilation scale can either be stored as header
information of the cell or in the meta objects M_CSCL.
If available these meta objects will be used to determine whether a so-called overscale
pattern shall be displayed, depending on the current display scale.
If no meta objects are available the compilation scale value stored in the cell header is
checked against the current display scale.

7.1.4 Viewing Groups

The purpose of viewing groups is to toggle the visibility of individual objects of the same
class. The EC2007 ECDIS Kernel provides a function to switch the status of the viewing group
or an interval of viewing groups to on or off. The respective objects will then be added to or
removed from the display.
For every S-52 lookup table entry a viewing group classification exists. This classification is
identified in the S-52 Presentation Library by a number between 0 and 99999. A list of all
viewing groups is given in the annex of the document EC2007_BackgroundInformation. The
viewing group of a certain object class can also be queried with the function
EcChartGetLookupEntry.
By handling viewing groups the chart presentation can be controlled to a wide extent, but it
requires profound knowledge and understanding of the S-57 object classes.
EcChartSetViewingGroup switches a particular viewing group or a set of viewing groups to on
or off. EcChartGetViewingGroup retrieves the status of a particular viewing group.

Following Viewing Group Layers are defined in the S-52 Presentation Library:

Drying Line

22010: CAUSWY, DAMCON, DYKCON

Buoys, beacons, aids to navigation

21010: Symbol fail

21020: NEWOBJ
22210: SLOTOP,
22220: AIRARE, BUAARE, BUISGL, CRANES, LNDMRK, PRDARE, SILTNK
22240: BUAARE
27010: BOYCAR, BOYINB, BOYISD, BOYLAT, BOYSAW, BOYSPP, LITFLT, MORFAC

79
EC2007 ECDIS Kernel Programming Guide

27011: LITVES
27020: BCNCAR, BCNISD, BCNLAT, BCNSAW, BCNSPP
27025: DAYMAR
27030: DISMAR
27040: M_NSYS
27050: TOPMAR
27060: GRIDRN
27070: LIGHTS
27080: FOGSIG, RETRFL
27210: RTPBCN
27230: RADRFL

Boundaries and limits

23030: SWPARE
26050: CTNARE, FAIRWY
26220: ACHARE, ACHBRT
26240: DMPGRD
26250: CTSARE, ICNARE

Prohibited and restricted areas

26010: RESARE,
26040: FERYRT, MIPARE, OSPARE, SPLARE, SUBTLN

Chart scale boundaries

11030: Chart scale boundary, overscale data [AP(OVERSCO1)]

Cautionary notes

26150: CTNARE

Ships’ routeing systems and ferry routes

25010: DWRTPT, PRCARE, ISTZNE, TSEZNE, TSSCRS, TSSLPT, TSSRON, TWRTPT, DWRTCL,
NAVLNE, RADLNE, RCRTCL, TSSLNE, TSSBND
25020: RCTLPT, RECTRC, RDOCAL
25030: FERYRT
25040: RADRNG
25060: RDOCAL

Archipelagic sea lanes

26260: ARCSLN

80
 EC2007 ECDIS Kernel Programming Guide

Spot soundings

33010: SOUNDG (S-52)

33012: SOUNDG (7Cs shallow)
33014: SOUNDG (7Cs deep)

Submarine cables and pipelines

34030: CBLARE, PIPARE

34070: CBLSUB, PIPSOL

All isolated dangers

34050: OBSTRN, LOGPON, UWTROC, WRECKS

34051: OBSTRN, WRECKS

Magnetic variation

31080: LOCMAG, MAGVAR

Depth contours

33020: DEPCNT

Seabed

33040: WATTUR
34010: SBDARE
34020: SPRING, WEDKLP

Tidal

33050: T_*
33060: TS_*

7.1.5 Date Dependent Objects

A date or date range

7.1.6 Other Mariner’s Settings

There are some viewing groups which are independent of the above defined view classes
(even though they are included in the numerical intervals). The presentation state of these
viewing groups will not be influenced by the function EcChartSetViewClass. For convenient
handling of these viewing groups the following functions are provided

[Link] Past Track

The past track can be visualized by displaying the special past track object.
EcChartSetShowPastTrack switches viewing groups 42410, 42430, 42440, 42460 on/off.

81
EC2007 ECDIS Kernel Programming Guide

[Link] Alternate Route

In an ECDIS it is possible to construct an entire network of routes but only one particular
route can be selected as the preferred route. In order not to overload the chart display it is
useful to hide all other routes making only the preferred route visible.
EcChartSetShowAlternateRoute switches viewing groups 42211 on/off.

[Link] Cross Track Limits

The cross track limits define a corridor around the legs of a route in which a vessel is
considered to be on track. Usually the legs of a route are displayed as lines because
displaying the areas that are defined by the cross track limits could overload the chart
display or might cover important objects in the vicinity of the route. The following functions
are used to control the visualization of the cross track limits. When the visualization is
switched on the areas defined by the cross track limits are drawn in a transparent color on
top of the legs of the route.
EcChartSetShowCrossTrackLimits switches viewing group 42212 on/off.

[Link] Symbol Fail

Another independent viewing group is defined by the PRESLIB to show symbolization errors.
A symbolization error occurs in case there is an unknown object class with no entry in the
lookup tables, or a chart object is not properly attributed. To handle symbolization errors the
following functions were developed:
EcChart[S|G]etShowSymbolFail switches viewing group 21010 on/off.

7.1.7 Other Chart Display Settings

Besides the mariner’s settings there are other settings the chart display can be changed or
configured with.

[Link] Depth Adjustments

In navigational charts all depth indications refer to a certain reference level. This is usually a
very low reference level, so that the indicated depth is also available at low water situations.
The EC2007 ECDIS Kernel provides the function EcChartSetDepthCorrection to adjust depth
values by defining a correction factor and offset to all features containing depth information
(e.g. depth areas, spot soundings, obstructions). The depth information of those features is
modified by the formula

correctedDepth = (originalDepth * correctionFactor) + correctionOffset

This formula is used within the conditional symbology procedures which handle the features
carrying depth information. This means that only the presentation of these features will
change if correction values are given.

82
 EC2007 ECDIS Kernel Programming Guide

Please note:
The actual data will not change, i.e. depth attributes of features and 3rd coordinates of
nodes will remain unchanged. The application must take care of this in case depth
information shall be presented in a pick report since the Kernel functions returning
feature information (e.g. EcQueryPickAll) will return the uncorrected depth values!

The default values are 1.0 for the factor and 0.0 for the offset, so the depth information
remains unchanged after the above formula has been applied.
The function EcChartGetDepthCorrection returns the current correction values for the
presentation of features carrying depth information.
The function EcChartSetDepthUnit may be used to set the depth unit. If the depth unit is set
to other than EC_DUNI_DEFAULT the chart image created by EcDraw[NT|X11]DrawChart will
contain text information, e.g. “Depths in Feet”. This default behavior can be switched off by
calling EcDrawSetShowDepthUnit.

[Link] Display Priority

Another parameter for switching the display of certain objects on or off is the display
priority. In the S-52 lookup tables there are the possible values 0 to 9. SevenCs uses a more
detailed list of 0 to 99. The defined display priority for a certain lookup table entry can be
queried with EcChartGetLookupEntry.
EcChartSetLayerVisible switches a display priority layer on/off.

[Link] Highlighting Objects

Besides the standardized highlighting functions for dangers the EC2007 ECDIS Kernel
provides the generic functions EcChartHighLightObject and EcChartSetHighlightInstruction.
These functions are used to specify an individual object that shall be drawn with the
highlight instruction after the next symbolization.
To find out whether the highlight status is set for a particular object of a given cell the
function EcChartIsHighLight can be used. This function returns True if the highlight status is
set and False if it is not set or an error occurred.
The highlighting can be switched off by passing the parameter False to the function
EcChartHighLightObject for each highlighted object in a given cell. It is, however, also possible
to switch off the highlighting of all objects in a given cell at once by means of the function
EcChartAllHighLightOff.
For a view there can be different symbolization instructions for point, line, and area objects.
To define these highlight instructions the function EcChartSetHighlightInstruction is used. The
parameters are:
• view Pointer to view structure
• dictInfo Not used
• primtyp Type of primitive (EC_A_PRIM, EC_L_PRIM or EC_P_PRIM)
• instruction String formatted according to Presentation Library (symbolization instruction)
For a descriptionof the instruction format please refer to the document
EC2007_BackgroundInformation.

83
EC2007 ECDIS Kernel Programming Guide

[Link] Better Usage Indicator

As described in chapter Chart Loading cells are loaded automatically according to their usage,
i.e. cells are drawn on top of each other. A grey outline indicates that a cell is already drawn
on top of cells with a lower usage. A magenta outline indicates that there is a better usage
available which will be drawn when zooming further in. Only the two next better usages are
indicated.
In the following example the approach cells which cover the river are already drawn on top
of the overview cell in which the river is only drawn as a line. The common outline of the
approach cells is displayed as a grey line. The magenta outlines indicate that there are
harbor cells available but not drawn yet. They will be drawn when zooming further in, i.e. at
a bigger display scale.

Figure 9: Better Usage Indicator

With the function EcChartSetShowUsages the display of the better usage indicator (magenta
line) can be switched on and off. The default is not to show the coverages.
In case the better usage indicator shall be drawn differently the function
EcDraw[X11|NT]DrawChartBoundary can be used.

[Link] Filtering Objects

The function EcChartFilterObject adds a group of feature objects to a filter set. As long as
there is a feature in the filter set it will not be symbolized. That means it will be invisible
after the next symbolization/drawing sequence. To make it visible again you must remove it
from the filter, and then symbolize and draw again.
Currently only the general filter is supported, i.e. all features that belong to the same object
class as the specified feature will be filtered.
The function EcChartFilterObjectClass adds all feature objects of the specified class to a filter
set. As long as there is a feature in the filter set, it will not be symbolized. That means it will
be invisible after the next symbolization/drawing sequence. To make it visible again you
must remove it from the filter, and then symbolize and draw again.

84
 EC2007 ECDIS Kernel Programming Guide

The function EcChartFilterAllObjects adds all feature objects to a filter set. This is particularly
useful in case only objects of a certain class shall be displayed. In this case
EcChartFilterAllObjects can be called to add all objects to the filter set. Then you can use
EcChartFilterObjectClass to remove the desired object class from the filter set. After the next
symbolization/drawing sequence only objects of the desired class will be visible.

7.1.8 Additional Mariner’s Information

To display special notes, information or drawings, a chart overlay to the existing chart image
has to be created (see chapter 7.2.1 Overlay Cells). In case the overlay cell approach is used
the EC2007 ECDIS Kernel uses the former S-52 mariner’s objects. For a list of possible
mariner’s objects please refer the document EC2007_Backgroundinformation. The
implementation of this approach is demonstrated in the examples testchart and
showOverlay.

7.1.9 Chart Drawing Settings

There are several parameters which influence the drawing of the charts. Following there are
some functions described which all in some way improve the legibility of the chart image.
For a complete list of functions please refer to the function group “Chart Drawing General”
in the function reference.

[Link] Set Symbol Filter

When the function EcDrawSetSymbolFilter is called to enable the symbol filter the Kernel
performs a check for every symbol before it is drawn. If a symbol would overlap an already
visible symbol of exactly the same shape, size and color then it will not be drawn. This has
two positive effects:
1. In most cases the drawing speed is increased because many symbols are suppressed,
and
2. The screen is less cluttered.
No information will be lost, because one symbol is still visible at the overlap position.

Please note:
This function considers soundings as well but does not guarantee that shallow soundings
are not suppressed by deeper soundings.
This function must not be applied in an ECDIS.

[Link] Text Settings

There are several functions EcDrawSetText… the text appearance can be configured with.

[Link] Scale Filter Warning

With the scale minimum Attribute (SCAMIN) S-57 / S-52 offer to suppress the display of
objects if the display scale has reached a certain value while zooming out. This reduces
clutter caused by the display of too many objects at small scales. With the function
85
EC2007 ECDIS Kernel Programming Guide

EcDrawSetShowScaleFilterWarning it is possible to display a warning text on the chart image.

This is to ensure that the user is aware of the fact that the chart contains more information
than currently displayed.

7.1.10 Default Values for Chart Settings

Safety Values
Safety Depth = 10.0
Safety Contour = 10.0
Deep Contour = 30.0
Shallow Contour = 5.0
Two Shades = false

Depth corrections
Depth factor = 1.0
Depth offset = 0.0
Depth units = use ENC units

Lights
Light display (viewing group 21010) = false
Light Radius Factor = 1.0
Light Distinction = true

Symbolization Time (DATSTA/DATEND)

Time correction = 0
Symbolize time = 0
Time is actual = true
Check date attributes = false

Other
Standard display (Viewing Groups 20000..29999,50000..59999) = true
Overscale pattern (Viewing Group 11030) = true
Important text only (Text Groups 10..19) = true
Symbol fail (Viewing Group 21010) = false
Past track (Viewing Groups 42410, 42430, 42440, 42460) = false
Alternate route (Viewing Group 42211) = false
Shallow pattern (Viewing Group 23010) = false
Cross track limits (Viewing Group 42212) = false
Sounding (Viewing Groups 33012, 33014) = false

86
 EC2007 ECDIS Kernel Programming Guide

Quality information (Viewing Group 31010) = false

Information points (Viewing Group 31030) = false
Official/unofficial chart boundaries (Viewing Group 11062) = false
Permit expiration warning (Viewing Group 11064) = false
Use Scamin = true
Show Coverage of Better Usage = false
Chart Datum = WGS84
Unicode Font = "Lucida Sans Unicode"
Cell Map Timeout = 0
Projection Buffer = false
Symbol Filter = false
Show Scale Filter Warning = true

7.2 Chart Overlays

Drawing chart overlays can either be implemented by directly using the function of the GUI
development tools or by using the EC2007 ECDIS Kernel functionality which is based on the
same approach like drawing charts. That means, that all overlay information are stored as
objects with attributes in a separate overlay cell, which will then be visualized as described
in chapter 12.2.3 Chart Symbolization and 12.2.4 Chart Drawing. The approach of overlay cells
also allows to exchange overlay information by means of the respective overlay cell.

7.2.1 Overlay Cells

Before any overlay can be drawn an overlay cell must be created which contains all the
objects. For a long time the IHO S-52 Standard contained a list of the so-called mariner’s
objects, e.g. own ship or waypoint. This is not the case anymore. IEC 62288 only describes
how navigation related objects shall be symbolized, it does not regulate how to implement
it. For the presentation of navigation related objects the EC2007 ECDIS Kernel still uses the
mariner’s objects. For a list of these objects please refer to the annex in the document
EC2007_BackgroundInformation.
SevenCs proposes to use different overlay cells for:
• dynamic objects, e.g. AIS or ARPA targets, the own ship, guard zone and past track
• static objects, e.g. the mariner’s notes, routes (waypoints and leglines)
For the overlay cell containing the static objects very often the term “user-defined objects”
(UDO) cell is used.

[Link] File-based Overlay Cell

The function EcChartOpenOverlayCell creates and maps a cell which will be used for chart
overlay drawings. Overlay cells are handled in a special way by the drawing functions: they
87
EC2007 ECDIS Kernel Programming Guide

are drawn on top of all other cells, regardless of their usages. This special behavior can be
used to implement dynamic features like weather or tidal overlay.
The function EcChartCloseOverlayCell closes and unmaps an overlay cell, and finally releases
the access.

Please note:
Overlay cells should not be imported into a DENC structure but loaded explicitly from
another directory.

Similar to the callback function for chart drawing in general (see chapter 6.6.8) there is a
callback function EcDrawSetOverlayCheckCallback for overlay drawings. Please refer to the
function reference for details.

[Link] Overlay Cell in RAM

For dynamic objects, i.e. objects which are frequently changing like AIS targets or the own
ship object, overlay cells can also be created in RAM with the function EcCellCreateInRam. An
example is given in the sample program showAIS.
aisCellId = EcCellCreateInRam( NULL, 0 );
if( aisCellId == EC_NOCELLID )
{ /* error handling */ }

// assign cell to view

if( !EcChartAssignCellToView( view, aisCellId ) )
{
EcCellUnmap( aisCellId );
// error handling
}

// lock cell
if( !EcChartCellLock( view, aisCellId, True ) )
{
EcChartUnAssignCellFromView( view, aisCellId );
EcCellUnmap( aisCellId );
// error handling
}

// set overlay flag

INT32 usage = EC_OVERLAY;
if( !EcCellSetHeaderInfo( aisCellId, EC_HDR_INTU, (caddr_t)&usage ) )
{
EcChartUnAssignCellFromView( view, aisCellId );
EcCellUnmap( aisCellId );
// error handling
}

88
 EC2007 ECDIS Kernel Programming Guide

7.2.2 Symbolizing and Drawing Overlay Cells

After the content of an overlay cell has been modified, e.g. by creation of a way point, the
overlay cell must be symbolized with EcChartSymbolizeCell. In case only a single feature has
been modified it is sufficient to symbolize only the feature with EcChartSymbolizeFeature.
After that the view can be drawn again with either EcDraw[NT|X11]DrawChart or with
EcDrawNTDrawCells in case separated pix maps are used for the chart background image and
the overlay image. The latter method performs faster.
If the projection buffer (see chapter Projection Buffer) is used for performance reasons it is
highly recommended to either
• have one view for the official read-only chart database, stored in the DENC structure, and
one view for cells which are used for overlay, or
• un-assign the overlay cell from the view with EcChartUnAssignCellFromView before the
content is changed and after that assign it to the view again with EcChartAssignCellToView
and lock it again with EcChartCellLock

7.3 Danger and Caution Highlight

7.3.1 Definition of danger and caution objects

With the introduction of the editions 4 of the IEC-61174 standard and the IHO Presentation
Library in 2015 an ECDIS has to distinguish between navigational hazards, areas for which
special conditions exists and safety contour related dangers. In the EC2007 ECDIS Kernel
these objects are defined in so-called danger dictionaries. The object classes included in
these files are categorized by the three key words NOTE, WARNING, and DANGER.
If EC_NOTE_LEVEL is specified all objects classes marked as NOTE, WARNING, and DANGER
within the danger dictionary will be evaluated when checking for dangerous objects.
If EC_WARNING_LEVEL is specified the object classes marked as WARNING and DANGER will
be considered when performing the check.
If EC_DANGER_LEVEL is specified only objects marked as DANGER will be searched for.
Following danger dictionaries are provided with the EC2007 ECDIS Kernel. However user
defined danger dictionaries can be created as well.
1. [Link]: Navigational hazards
2. [Link]: Areas for which special conditions exists
3. [Link]: Safety contour related dangers
4. [Link]: previous generic danger dictionary
For route checking and monitoring these danger dictionaries have to be read with the
function EcQueryReadDangerDictionary. This function returns a pointer to a danger dictionary
context of type EcDangerInfo. The danger catalogue file must reside in the path
$LIB_7CS/lib/objcat.
If it is no longer needed the returned danger dictionary context must be freed by the
application using the function EcQueryFreeDangerDictionary.

89
EC2007 ECDIS Kernel Programming Guide

7.3.2 Detection and notification of danger and caution objects

Danger and caution objects can be detected by the functions EcRouteCheckExt (see 7.5.5) or
EcMonitorCheckGuardZone (see [Link]). Depending on the passed danger dictionary both
functions return a list of features which can be passed to the highlight function
EcDraw[NT][X11]HighlightDangers. According to the IHO Presentation Library safety contour
related dangers shall be highlighted in red (useDangerSymbol = True), areas for which
special conditions exists and navigational hazards in yellow (useDangerSymbol = False).

7.4 Indication of Automatic Updates

With the new editions 4.0 of the IHO Presentation Library and the IEC 61174 Standard the
mariner must be able to not only review single updated objects but also all objects which
have been updated in a certain date range. In addition not only the recent object shall be
indicated but also former states of the object, e.g. former extensions of areas.
For this reason a new type of SENC file has been introduced, the so-called SENC history file
with the extension 7UH.
The compilation of the SENC history files during the chart import has to be enabled with the
function EcS57V3SetUpdateHistoryMode.
In case ENC updates have been applied with the update history mode and SENC history files
have been compiled the updates can be reviewed with the function
EcDraw[NT][X11]HighlightUpdateHistory.
An example implementation of the update indication can be found in the Qt based example
program showHistory.

7.5 Route Handling

The technology of the Electronic Chart Display and Information System (ECDIS) is used by the
mariner in the same way as the traditional paper sea chart: to navigate his vessel from port
A to port B. Therefore ECDIS supports the same kind of chart work as the paper chart but in
a digital and much more flexible way.
On the paper chart the actual route is planned with pencil, divider, and ruler after erasing all
alternative routes. All electronic aids for navigation (e.g. Satellite Navigators) support this
concept and allow old routes to be stored but only one route to be loaded and used: the
preferred and actual route.
A different concept is supported by ECDIS: The elements of route planning in ECDIS are the
waypoints and the leg lines or legs which connect the waypoints. While waypoints may stand
alone legs are always bounded by waypoints. Legs are connected to exactly two waypoints,
one at each end. However, a waypoint may be connected to any amount of leg lines. This
makes a waypoint a node in a network of leg lines. The routes used during a voyage can be
connected at significant waypoints to build a route network. Waypoints and legs in an ECDIS
carry more information than their counterparts in the paper chart. Legs can be constructed
for a preplanned speed, and waypoints carry information about the turning radius of the
next course change etc.

90
 EC2007 ECDIS Kernel Programming Guide

But how will the mariner find his way through this network of leg lines and waypoints? ECDIS
provides two kinds of leg lines and waypoints: Those belonging to a preferred route (i.e. the
actual route taken), and those belonging to alternate routes.
The source code examples given in the following chapters have been extracted from the
sample program showRoute.

7.5.1 Creating Routes

During planning a voyage in an ECDIS legs and waypoints are created. So-called alternate
routes are connected at waypoints to form a network of leg lines. These represent all the
routes a vessel may use during her voyage. The SevenCs EC2007 ECDIS Kernel provides
functions to easily construct such a route network.
In an ECDIS the waypoints and leg lines are realized as feature objects of the class ‘waypnt’
and ‘leglin’, respectively. For more information about their possible attributes and attribute
values please refer to the document BackgroundInformation.
These feature objects are created and inserted into an overlay cell which has been created
with EcChartOpenOverlayCell (see chapter Overlay Cells).
With the function EcRouteAddWaypoint a new waypoint feature object can be created. The
parameters are:
• cellid Identifier of a mapped cell (overlay cell)
• dictInfo Pointer to an object dictionary context
• lat Latitude of the waypoint in degrees
• lon Longitude of the waypoint in degrees
• pickRad Radius to search for other waypoints in nautical miles
• turnRad Turning radius of the waypoint in nautical miles
The parameters lat and lon specify the position of the new waypoint object. If a waypoint
already exists at the specified position or in the near vicinity that is defined by the pickRad,
no new waypoint will be created. If the specified position is on or in the near vicinity of a leg
line this leg will be split into two legs with the new waypoint inserted and connected to both
leg lines. The function returns a handle of either the newly created or the already existing
waypoint object.

Please note:
This function not always creates exactly one new feature object. If for example a
waypoint already exists at the specified position no waypoint feature object will be
created; or if a waypoint is inserted into an existing leg this will be split, and an additional
legline feature object created. It is important to keep this in mind when considering the
symbolization of the entire cell or a single feature object.

To create a new leg line between two given waypoints the function EcRouteAddLegline is
used. The parameters are:
• cellid Identifier of a mapped cell (overlay cell)
• dictInfo Pointer to an object dictionary context

91
EC2007 ECDIS Kernel Programming Guide

• datum Horizontal datum

• wp1 Handle of a waypoint feature object at the start of the leg line
• wp2 Handle of a waypoint feature object at the end of the leg line
• speed Speed planned on the leg in knots
• legType Type of leg line, i.e. EC_RUMBLINE or EC_GREATCIRCLE
This function creates a leg line with the specified characteristics. The two given waypoint
objects form the start and end waypoints of the created leg line. If a leg already exists
between these two waypoints no new leg line will be created, and the handle of the existing
leg will be returned by this function. With the macro ECOK the returned handle can be
checked for success.
char *cellName = "ROUTES.7CB"; // has to be defined including path
EcCellId routeCid;
EcDictInfo *dictInfo;
EcFeature wp1, wp2, leg;
EcView *view;
EcCoordinate lat, lon;
int datum, legType;
double range, pickRad, turnRad, speed;

/* the dictionary context and the view have been created

in previous steps */

// create a new overlay cell

routeCid = EcChartOpenOverlayCell(view, cellName, EC_ACCESSWRITE);
if (routeCid == EC_NOCELLID)
{ /* error handling */ }

pickRad = 0.03 * range;

turnRad = 5;
datum = EC_GEO_DATUM_WGS84;
legType = EC_RHUMBLINE;
speed = 10;

if (first) // first clicked waypoint

{
// create first waypoint
wp1 = EcRouteAddWaypoint(routeCid, dictInfo, lat, lon,
pickRad, turnRad);
if (!ECOK(wp1))
{ /* error handling */ }
first = False;
}
else // next clicked waypoint
{
// create next waypoint
wp2 = EcRouteAddWaypoint(routeCid, dictInfo, lat, lon,
pickRad, turnRad);
if (!ECOK(wp2))
{ /* error handling */ }

92
 EC2007 ECDIS Kernel Programming Guide

// create legline between the two waypoints

leg = EcRouteAddLegLine(routeCid, dictInfo, datum, wp1, wp2,
speed, legType);
if (!ECOK(leg))
{ /* error handling */ }
// set current waypoint as first waypoint
wp1 = wp2;
}

……

// close the overly cell

EcChartCloseOverlayCell(view, routeCid);

In case different widths shall be assigned following functions can be used. With
EcRouteSetLegLineXtrack the corridor width of one side of the leg line can be set. By means of
the function EcRouteLegLineIsVertical the Kernel assigns the value to the right side which can
later be reproduced for the drawing and checking functions. An example is given in the
sample program showroute.

7.5.2 Deleting Routes

The EC2007 ECDIS Kernel software also provides functions to remove leg lines and
waypoints. With the function EcRouteDeleteLegLine a leg line feature object can be deleted.
The parameters are:
• dictInfo Pointer to an object dictionary context
• leg Handle of the leg line object to be deleted
The function only deletes a leg line feature object in case this does not belong to a selected
(preferred) route (see below for details on selecting a route). The waypoints that are
connected to the specified leg will not be touched. The function returns True on success and
False otherwise.
The function EcRouteDeleteWaypoint is used to delete a waypoint feature object. The
parameters are:
• dictInfo Pointer to an object dictionary context
• waypoint Handle of the waypoint object to be deleted
Since a legline cannot exist without its bounding waypoints, all leg lines that are connected
to the specified waypoint will be deleted as well. As with the function EcRouteDeleteLegline,
only waypoint objects that do not belong to a selected route can be deleted. If a selected
waypoint is specified the function returns False, and True on success.

93
EC2007 ECDIS Kernel Programming Guide

7.5.3 Changing Routes

Apart from creating and deleting waypoints and leg lines there is also an EC2007 ECDIS
Kernel function which enables an existing waypoint to be moved to a new position. The
function is called EcRouteMoveWaypoint, and the parameters are:
• cellid Identifier of a mapped cell (overlay cell)
• dictInfo Pointer to an object dictionary context
• datum Horizontal datum
• waypoint Handle of the waypoint object to be moved
• newlat New latitude of the waypoint in degrees
• newlon New longitude of the waypoint in degrees
• pickRadius Radius to search for other waypoints in nautical miles
This function moves the specified waypoint to the new position including all its attached leg
lines. If there is already a waypoint located at the given position or in the near vicinity the
two waypoints will be merged into one. This is realized by removing the specified waypoint
and connecting all its legs to the already existing waypoint. The function returns True on
success and False otherwise.

Please note:
The function EcRouteMoveWaypoint, unlike the functions EcRouteDeleteLeg and
EcRouteDeleteWaypoint, does not take into account that a specified waypoint is part of a
selected route. Since it is not intended that a preferred route can be changed in any way,
the application needs to check if the specified waypoint is selected or not.

The state of a waypoint or leg line feature object is stored in its attribute ‘select’. The value 1
indicates that the object is part of a ‘planned’ or preferred route, value 2 indicates that the
object is part of an ‘alternate’ route, and 0 indicates an ‘undefined’ state. The following
example shows how to get the state of a waypoint or leg line feature object. In case the
object is part of a preferred route True is returned, if the object is part of an alternate route
or if the state is undefined False is returned.
Bool isSelected(EcFeature feature)
{
char attrStr[256];

if (EcFeatureQueryAttribute(feature, dictInfo, "select", attrStr,

sizeof(attrStr)))
{
if (strcmp(attrStr, "select1")==0)
return True;
}
return False;
}

94
 EC2007 ECDIS Kernel Programming Guide

7.5.4 Selecting Routes

After having planned routes the preferred route (the route that the vessel will use) has to be
selected from the constructed route network. This route will become the selected or
monitored route. All other routes are kept as alternate routes.

Please Note:
By default alternate routes are note displayed. To display them use the function
EcChartSetShowAlternateRoute

In an ECDIS all waypoints and leg lines that belong to such a preferred route are stored in a
special collection feature object of type aggregation. The function EcRouteInit creates such a
feature object. The object class is C_AGGR (aggregation), and the attribute INFORM is set to
‘EC_ROUTE’. The function takes an identifier of a mapped cell and a pointer to a dictionary
context as parameters and returns a handle of an empty route feature object.
This route object is needed when selecting a preferred route from the network of waypoints
and leg lines. The function EcRouteSelect is used to alternately fill the route collection object
with waypoint and leg line objects. The parameters are:
• dictInfo Pointer to an object dictionary context
• route Handle of route feature object
• startObj Handle of start feature object (waypoint or leg line)
• endlat Latitude of last selected waypoint in degrees
• endlon Longitude of last selected waypoint in degrees
The selection always starts with a waypoint feature object and stops in case the way through
the network becomes ambiguous, or an end waypoint is reached. However, by passing a leg
line feature object that is connected to the last waypoint of an already selected route the
selection process can be continued. It is also possible to extend an already selected route by
passing the last waypoint of the already selected route as start object. The return value of
this function is as follows:
• 0 on success (end waypoint was reached)
• 1 on unambiguous continuation (next leg line needs to be specified)
• <0 on error (e.g. specified leg line is not connected to the last waypoint of an already
selected route)

Please note:
If a waypoint that is not the end waypoint of an already selected route is specified as
start object a new preferred route will be started from that point.

It is, however, possible to select more than one preferred route. This can be realized by
creating additional route feature objects by means of the function EcRouteInit.

95
EC2007 ECDIS Kernel Programming Guide

7.5.5 Checking Routes

After having selected a preferred route it is necessary to prove that this route fulfils given
safety criteria. There are at least two reasons:
1. The mariner who is responsible for navigation and route planning has to follow external
criteria.
2. The ECDIS generalizes the display of the chart at smaller scales and even loads chart
data depending on the scale. Therefore the mariner may not see all dangers if he uses
the wrong scale for route planning.
It is not easy to define criteria to optimize a route but there is a set of minimum
requirements a route has to fulfill for every vessel in every trade:
• A preferred route should not cause the grounding of a vessel.
• A preferred route should not cause the collision of the vessel with floating or fixed objects
or obstacles.
• A preferred route should take into account that the vessel may deviate more or less from
the route.
Therefore three parameters are defined representing the safety requirements mentioned
above. The values of the parameters must be adjusted to the respective vessel:
1. safety draught
2. safety air draught
3. safety distance or cross track limit (defined by the attribute ‘xtrack’ of the leg line
object)
These safety values are the basis for the route check and are therefore passed to the
function EcRouteCheckExt. This function checks a preferred route and takes the following
parameters:
• safeDepth Safety depth in meters
• airDraft Air draught in meters
• safeDist Safety distance in nautical miles
• datum Horizontal datum
• dictInfo Pointer to an object dictionary context
• dngInfo Pointer to a danger dictionary
• route Handle of the route object
• catList Pointer to a cell catalogue list
• addCellList Array of mapped cell IDs which should be checked additionally to the loaded
cells
• numOfCells Number of additional cells
• view Pointer to view context
• leg Pointer to last leg or leg where dangers occurred
• dngobjs Pointer to array of dangerous feature objects

96
 EC2007 ECDIS Kernel Programming Guide

• checkCurve Flag to check curved legs or straight legs at way points

• highlight Flag to highlight of dangerous features
• autoCTL Flag to automatically select the largest value for safety distance or cross track
limit
The first three parameters of this function specify the above mentioned safety values. These
are dependent on the vessel currently using the ECDIS and the judgement of the mariner.
The parameter dngInfo is a pointer to a danger dictionary context of type EcDangerInfo as
returned by the function EcQueryReadDangerDictionary. With the introduction of the editions
4 of the IEC-61174 standard and the IHO Presentation Library in 2015 different danger
dictionaries have to be used (see chapter 7.3).
The pointer to a cell catalogue list (catLst) of type EcCatList, which is returned by the
function EcCellCreateCatalogueList, is required to load all needed cells from the cell catalogue.
If any additional cells are to be checked they have to be explicitly passed to the function in
an array of cell IDs (parameters addCellList and numOfCells).
Depending on which value shall be taken for the route check following parameters have to
be set:
• Safety distance: safeDist = value, autoCTL = false
• Cross track limit attribute: safeDist = 0, autoCTL = false
• Largest value of both: safeDist = value, autoCTL = true
If manual update features shall be checked as well the function EcRouteCheckManUpd has to
be used instead of EcRouteCheckExt.
If any dangerous objects are encountered during the route check the corresponding cells
from the cell catalogue will be loaded into the specified view, and the dangerous objects
along the route will be highlighted. Also the leg line object where the first dangerous object
was found will be returned into the parameter leg. All dangerous objects found along the
route will be returned into the array dngobjs, including those found in the given additional
cells that are not loaded into the view. The return value of this function is the number of
dangerous objects stored in this parameter. In case no dangerous objects are found the
function will return 0 and -1 if an error has occurred.

Please note:
This function allocates memory to the array of dangerous feature objects dngobjs, which
must be freed by the application when it is no longer needed using the function EcFree.

In case the route check encounters a violation of the safety parameters the route has not
been properly planned and must be corrected. The selected route can be partially
deselected from the point where the first dangerous object was encountered by passing the
returned leg feature object to the function EcRouteReleaseLegLine. This part of the route can
then be modified (see chapter Changing Routes). After correcting the route it has to be
selected and checked again until the entire course of the route is free of dangerous objects.
After the preferred route has been successfully checked it may be useful to save it into a file
using the function EcRouteExport and / or to create a waypoint list showing all waypoints of
the preferred route as well as the distances and bearings to the respective next waypoint.

97
EC2007 ECDIS Kernel Programming Guide

To realize such a
waypoint list of the preferred route first the function
EcRouteGetPlannedWaypoints can be used to retrieve all waypoints of a preferred route one
by one. The parameters are:
• route Handle of the route object
• dictInfo Pointer to an object dictionary context
• fi Buffer of type EcFindInfo to store the iteration state
• first Flag indicating first or subsequent calls (EC_FIRST or EC_NEXT)
The function returns a handle of a waypoint feature object which can be checked with the
macro ECOK. If no route object exists the function returns an empty handle.
To get the name of a waypoint object the value of its attribute OBJNAM has to be retrieved
from the object’s attribute list. This is realized with the functions EcFeatureQueryAttribute
and EcDictionaryTranslateAttributeValue (see chapter Attributes).
The latitude and longitude of the waypoint’s position can be retrieved by means of the
function EcObjectGetLocation, and the returned values can be converted into a string using
the function EcOutPositonToString. More information about each waypoint like its turning
radius is stored in the object’s attributes and can be retrieved just like the name.
The following example shows how to get the information of the first waypoint using the
functions mentioned above, and how to write this information into a string.
EcFeature firstWp;
char attribute[42], buffer[255], wpString[500];
EcCoordinate lat, lon;
double depth;
EcFindInfo wpfi;

// get the first waypoint of the preferred route

firstWp = EcRouteGetPlannedWaypoints(route,dictInfo,&wpfi,EC_FIRST);
if (!ECOK(firstWp))
return;
// get the name of the first waypoint
if (EcFeatureQueryAttribute(firstWp, dictInfo, "OBJNAM", attribute,
sizeof(attribute)))
{
EcDictionaryTranslateAttributeValue(dictInfo, attribute, buffer,
sizeof(buffer));
sprintf(wpString,"%-15.15s ", buffer);
}
// get the position of the first waypoint
if (EcObjectGetLocation(firstWp, EC_CENTERPOS, &lat, &lon, &depth))
{
EcOutPositionToString(buffer, lat, lon, 1);
strcat(wpString, buffer);
}
…

98
 EC2007 ECDIS Kernel Programming Guide

To calculate the distance and course to go to the next waypoint the legline between the
current and the next waypoint is needed. The function EcRouteWaypointGetLegLines is used
to retrieve all legline objects connected to a given waypoint. The parameters are:
• waypoint Handle of the waypoint object
• dictInfo Pointer to an object dictionary context
• fi Buffer of type EcFindInfo to store the iteration state
• first Flag indicating first or subsequent calls (EC_FIRST or EC_NEXT)
• otherlat Latitude of other end of leg
• otherlon Longitude of other end of leg
The function returns a handle of a leg line object connected to the given waypoint. The
macro ECOK should be used to check whether the handle is valid or no more leg lines have
been found. The parameters otherlat and otherlon additionally hold the position of the
waypoint connected to the other side of the returned leg line.
In the example above the name and position of the first waypoint is retrieved. The next step
is to retrieve the next waypoint and all its leg lines. For each leg line it is then checked if the
position of the waypoint connected at the other end is equal to the position of the previous
waypoint of the preferred route.
EcFeature nextWp;
EcCoordinate prevlat, prevlon;
EcFindInfo legfi;
Bool legFound = False;

…
// get the next waypoint of the preferred route
nextWp=EcRouteGetPlannedWaypoints(route, dictInfo, &wpfi, EC_NEXT);
while (ECOK(nextWp))
{
// get the legline between the current and the next waypoint
leg=EcRouteWaypointGetLegLines(nextWp, dictInfo, &legfi, EC_FIRST,
&prevlat, &prevlon);
while ((ECOK(leg)) && (!legFound))
{
// check if legline is connected to previous waypoint
if ((lat == prevlat) && (lon == prevlon))
legFound = True;
// get the next legline of the waypoint
leg=EcRouteWaypointGetLegLines(nextWp,dictInfo,&legfi,EC_NEXT,
&prevlat,&prevlon);
}
…
}

With the leg object and the position of the start and end waypoints the distance and bearing
between these waypoints can be calculated. The calculation of the distance and bearing
between two points depends on the line characteristic on the earth’s surface, rhumbline or
great circle. A rhumbline or loxodrome is a line crossing all meridians of longitude at the

99
EC2007 ECDIS Kernel Programming Guide

same angle, whereas (the minor arc of) a great circle is the shortest surface-path between
two points.
The legline characteristic is stored in the attribute ‘legchr’ of the leg object. To retrieve its
value the functions EcFeatureQueryAttribute can be used. The attribute ‘legchr’ is of type
enumeration. The value 1 stands for rhumbline, and value 2 for great circle.
In the function set EC27_Navigation of the EC2007 ECDIS Kernel there are two functions to
calculate the distance and bearing between two points:
EcCalculateRhumblineDistanceAndBearing for the line characteristic rhumbline and
EcCalculateGreatCircleDistanceAndBearing for the line characteristic great circle. The functions
take the same parameters, except that a start and end bearing is calculated for the line
characteristic great circle. The parameters are:
• datum Local horizontal datum
• lat1 Latitude of start position
• lon1 Longitude of start position
• lat2 Latitude of end position
• lon2 Longitude of end position
• dist Distance in nautical miles
• course Bearing in nautical degrees ([startCourse] start bearing for great circle)
• [endCourse] For great circle only; end bearing in nautical degrees
Below is the continued example for creating a waypoint list. With the leg object between the
current and the next waypoint the distance and course to go to the next waypoint is
calculated and concatenated to the string holding the information about the current
waypoint.

double dist;
double startCourse, endCourse;
…
// get the position of the next waypoint
EcObjectGetLocation(nextWp, EC_CENTERPOS, &lat, &lon, &depth))

if ((legFound) && (ECOK(leg)))

{
// get the leg characteristics
if (EcFeatureQueryAttribute(leg, dictInfo, "legchr", attribute,
sizeof(attribute)))
{
if (strcmp(attribute, "legchr1")==0) // rhumb line
EcCalculateRhumblineDistanceAndBearing(
DATUM, prevlat, prevlon, lat, lon, &dist, &startCourse);
else // great circle
EcCalculateGreatCircleDistanceAndBearing(DATUM, prevlat,
prevlon, lat, lon, &dist, &startCourse, &endCourse);
// convert distance to go to string
EcOutDistanceToString(dist, buffer, sizeof(buffer));

100
 EC2007 ECDIS Kernel Programming Guide

strcat(wpString, buffer);
// convert course to go to sting
EcOutBearingToString(startCourse, buffer, sizeof(buffer));
strcat(wpString, buffer);
if (strcmp(attribute, "legchr2")==0) // great circle
{
EcOutBearingToString(endCourse, buffer, sizeof(buffer));
strcat(wpString, " -> ");
strcat(wpString, buffer);
}
}
legFound = False;
…
}

The functions EcOutDistanceToString and EcOutBearingToString append the unit nautical miles
(nm) or nautical degrees (°) respectively to the converted distance and bearing values. These
two functions are combined in the function EcOutDistanceAndBearingToString. These and
additional conversion and formatting functions are included in the function set
EC27_Navigation.
In the example the string wpString now holds the name and position of the current
waypoint, and the distance and course to the next waypoint. In addition, the planned speed,
which is stored in the attribute ‘plnspd’ of the leg line object, could be appended. This string
can then be printed or displayed in a dialogue window for each waypoint of the preferred
route.

7.5.6 Clearing Routes

Preferred routes may be cleared or partially cleared if necessary. The functions that support
clearing are EcRouteClear and EcRouteReleaseLegLine.
The function EcRouteClear deselects the entire route. The parameters are:
• route Handle of route feature object
• dictInfo Pointer to an object dictionary context
The route feature object itself is not deleted and can be used to select a new route as
described above.
The function EcRouteReleaseLegLine is used to partially deselect a preferred route. The
parameters are:
• route Handle of route feature object
• dictInfo Pointer to an object dictionary context
• legline Handle of leg line feature object
The parameter leg line specifies the point from which the preferred route is deselected, i.e.
the specified leg and all following waypoints and leg lines of the preferred route are
deselected. If the first leg line of a route is passed to this function the entire route will be
cleared including the first waypoint.

101
EC2007 ECDIS Kernel Programming Guide

To retrieve all route feature objects of a given cell one by one the function EcRouteSpot is
used. This function takes the following parameters:
• cellid Identifier of a mapped cell (overlay cell)
• dictInfo Pointer to an object dictionary context
• fi Buffer of type EcFindInfo to store the iteration state
• first Flag indicating first or subsequent calls (EC_FIRST or EC_NEXT)
The return value of this function is a handle of a route feature object available in the given
cell. To retrieve all route objects of the given cell this function should first be called with
EC_FIRST as parameter, and all subsequent calls with EC_NEXT as parameter. When no more
route objects are available the returned value is an empty handle. The macro ECOK can be
used to check whether the returned object is valid.
After the preferred route has been determined showing all alternate routes of the network
may overload the chart display and distract from the preferred route. The EC2007 ECDIS
Kernel therefore allows to switch off the display of the alternate routes, with only the
preferred route remaining visible on the chart display. The function
EcChartSetShowAlternateRoute is used to realize this (see chapter Date Dependent Objects
A date or date range
Other Mariner’s Settings).

7.5.7 Exchanging Routes

To permanently save and reuse a route network and a selected route the EC2007 ECDIS
Kernel provides functions to export and import all waypoint, leg line, and route feature
objects of a given cell. The function EcRouteExport writes all preferred and alternate routes
into an S-57 file. The parameters are:
• cellid Identifier of a mapped cell (overlay cell)
• dictInfo Pointer to an object dictionary context
• fileName Name of the export file
The route export file that is created with this function can be imported by other ECDIS
systems enabling other vessels to use the constructed route network and selected preferred
route.
The function EcRouteImport reads all preferred and alternate routes from the specified SENC
file. The parameters are:
• cellid Identifier of a mapped overlay cell to which the route shall be copied
• dictInfo Pointer to an object dictionary context
• fileName Name of the export file

Please note:
All route, waypoint, and legline objects already existing will be removed from the given
cell and replaced by the objects in the specified file.

102
 EC2007 ECDIS Kernel Programming Guide

7.5.8 Route Database

For the use of ECDIS it might be necessary to enable mariners to calculate routes with regard
to certain optimization criteria. For example, sometimes it may be possible to reach a harbor
in more than one way. But which route is the best, the fastest or shortest?
According to the existing standard feature objects of the object class “waypnt” and “leglin”
are labeled with certain attributes. In theory each of these attributes can be used as an
optimization criterion. A first approach to this concept is the well-known Dijkstra-Algorithm
which is implemented with time complexity O(n^2) and a small set of optimization criteria.
For creating optimum routes a predefined knowledge database delivered from SevenCs is
necessary. This knowledge database is a finite graph consisting of waypoints (in this context
called “nodes”) and legs labeled with their standard attributes. All questions of routing will
be answered with the help of this routing network!
The route database is contained in the SENC file WorldRoutes.7CB which is located in
$EC2007/data/Routes.

[Link] Database Initialization

The routing network must be initialized before the calculation can be started. The
initialization makes the routing network accessible for all functions within this function
group.
To map the routing network the function EcRoutingInitDatabase is used.
The parameters are:
• networkName Directory of routing network
• di Pointer to an object dictionary context
This function loads all cells from the defined directory, extracts the waypoints and leg lines
and returns a routing database which represents hidden and necessary information for the
optimization. All other functions of this group need this routing object as a parameter!
To delete routing objects call the function EcRoutingFreeDatabase.

[Link] Database Queries

For querying information about the routing network the following functions can be used:
• EcRoutingGetAllObjects
• EcRoutingQueryNode
• EcRoutingQueryLeg
• EcRoutingGetNearestNodes
• EcRoutingGetNearestLegs
By means of the function EcRoutingGetAllObjects attribute values and information on all
nodes and/or legs from the current routing object can be retrieved.
The function EcRoutingGetAllObjects takes the following parameters:
• ro Pointer to routing object

103
EC2007 ECDIS Kernel Programming Guide

• di Pointer to an object dictionary context

• nodeInfos Returned list of all nodes of the routing object
• nNodeInfos Returned number of nodes in list
• legInfos Returned list of all legs of the routing object
• nlegInfos Returned number of legs in list
Memory is allocated by the function and must be freed with EcRoutingFreeNodeInfos and
EcRoutingFreeLegInfos.

The structure EcRoutingNodeInfo contains following members:

• EcRoutingNodeName name Node name (OBJNAM)
• EcCoordinate lat, lon Coordinates of node
• double turningRadius Turning radius for this node
• int type Type of waypoint
The structure EcRoutingLegInfo contains following members:
• EcRoutingLegName name Leg name (combination of start/end node names)
• EcCoordinate staLat, Start/end coordinates of leg
staLon, endLat, endLon
• Bool isGreatCircle Flag whether leg is great circle or rhumbline
• double plannedSpeed Planned speed for this leg

The function EcRoutingQueryNode retrieves all information about exactly one waypoint. The
necessary parameters are:
• ro Pointer to routing object
• di Pointer to object dictionary context
• node Name of node to retrieve information
• nodeInfo Returned list of all found information
Memory is allocated by the function and must be freed with EcRoutingFreeNodeInfos and
EcRoutingFreeLegInfos.
The function EcRoutingQueryLeg operates accordingly.
The function EcRoutingGetNearestNodes calculates a list of nodes which are closest to a user-
defined lat/lon position. Thus it offers the possibility to find the nearest “entry nodes” of the
routing network for further calculation. The parameters are the following:
• ro Pointer to routing object
• di Pointer to an object dictionary context
• lat Latitude of search position
• lon Longitude of search position

104
 EC2007 ECDIS Kernel Programming Guide

• nodeInfo Returned list of nearest nodes

The function EcRoutingGetNearestLeg operates accordingly.
The returned value result is the number of found closest nodes. In general the value is one.
However, in some special cases there may be more than one closest node:
Imagine a user-defined lat/lon position exactly in the center of a graph consisting of four
nodes and four legs defining a quad. In this special case the list of closest nodes will contain
four items!

Please note:
Memory is allocated by all query functions and must be freed with
EcRoutingFreeNodeInfos and/or EcRoutingFreeLegInfos.

The following example shows how to initialize the route database and to query information:
EcDictInfo *di;
EcRouting *routing;
EcRoutingNodeInfo *nodeInfo;
EcRoutingLegInfo *legInfo;
int nNodes, nLegs;
Bool found;

// initizialize the routing object

EcRoutingNetworkName routeDir = "C:/EC2007/5.14/data/Routes";
routing = EcRoutingInitDatabase(routeDir, di, NULL);

// get all nodes (waypoints) and leglines from the routing object
found = EcRoutingGetAllObjects(routing, di, &nodeInfo, &nNodes,
&legInfo,&nLegs);

// get all information about the node with the name "Elbe 5" (OBJNAM)
EcRoutingNodeName currentNodeName = "Elbe 5";
found = EcRoutingQueryNode(routing, di, currentNodeName, &nodeInfo);

// get the nearest node[s] to the position (usually only one node)
EcCoordinate lat = 43.373668;
EcCoordinate lon = 8.683521;
nNodes = EcRoutingGetNearestNodes(routing, di, lat, lon, &nodeInfo);

[Link] Database Modification

Sometimes it may be necessary to adapt the routing network delivered by SevenCs to your
own purposes. The following functions allow for adding, moving or deleting feature object
and attributes of the routing network.
They are also responsible for avoiding inconsistencies: if the user wants to change the
attribute “OBJNAM” of a node it must be ensured that the change does not lead to any
contradiction. It is essential that object names of nodes in the routing network are unique!
Moreover it is impossible to move or to delete so-called crosspoints. Crosspoints are special
waypoints in the routing network delivered by SevenCs which make it easier to manage the
routing network and calculate optimizations.

105
EC2007 ECDIS Kernel Programming Guide

The functions for database modification are EcRoutingModifyNodes and EcRoutingModifyLegs.

The parameters of function EcRoutingModifyNodes are:
• ro Pointer to routing object
• di Pointer to an object dictionary context
• action EcRoutingAdd, EcRoutingMove, EcRoutingDelete
• node List of nodes to be changed
• nodeInfo List of information to be changed
• nNodes Number of nodes in list
The following matrix describes the behavior of the function EcRoutingModifyNodes in
accordance to the user-defined parameter settings (“X” indicates that this parameter must
be mandatorily set).

106
 EC2007 ECDIS Kernel Programming Guide

Action node nodeInfo behavior

EcRoutingAdd X X If the nodes exist in the routing network the node
information will be changed according to the
settings of nodeInfo.
If the nodes do not exist new nodes will be created
with the information defined in nodeInfo.
EcRoutingMove X X Moves existing nodes to the lat/lon coordinates
defined in nodeInfo. If a node at the new
coordinate already exists both nodes will be
merged.
EcRoutingDelete X NULL Deletes existing nodes.

It is important to understand that this function works according to the principle all or
nothing, i.e. before making any changes the function will check whether all nodes in the
node list are changeable.
Imagine the following example:
There are three nodes in the current node list and the parameter action is set to
EcRoutingMove. The function then realizes that one of the three nodes does not exist in the
routing network. Thereupon the function will return False to indicate that one desired
movement is impossible.
The following example is more complicated:
There are five nodes in the current node list, and the parameter action is set to
EcRoutingAdd. The function realizes that the object names of two nodes from the list shall be
changed to object names which still exist within the routing network. Since this is impossible
the function will return False to indicate that nothing has been changed.
The parameters of function EcRoutingModifyLegs are:
• ro Pointer to routing object
• di Pointer to an object dictionary context
• action EcRoutingAdd, EcRoutingDelete
• leg List of legs to change
• legInfo List of information to change
• nLegs Number of legs in list
The following matrix describes the behavior of this function in accordance to the user-
defined parameter settings (“X” indicates that this parameter must be mandatorily set).

107
EC2007 ECDIS Kernel Programming Guide

Action leg legInfo Behavior

EcRoutingAdd X X If the legs exist in the routing network the leg
information will be changed according to the settings
of legInfo.
If the leg does not exist new legs will be created with
the information defined in nodeInfo
EcRoutingDelete X NULL Deletes existing legs.

It is important to understand that this function works according to the principle all or
nothing: i.e. before making any changes the function will check whether all nodes in the
node list are changeable.
Some more examples to understand the behavior:
There are five legs in the current leg list, and the parameter action is set to EcRoutingAdd.
The function “realizes” that the start and end coordinates of the legs are connectable to
existing waypoints, then constructs the legs in the routing network and returns True to
indicate the all changes have been carried out.
If in this special case at least one leg is defined with start coordinates which are far away
from an (essential!) waypoint the result False will be returned to indicate that nothing has
been changed.

Please note:
Legs cannot be moved! If you want to move legs move one of the attached nodes using
EcRoutingModifyNodes with the parameter EcRoutingMove. The leg will then be moved
automatically.

[Link] Database Calculation

After initialization and adaptation of the routing network it is possible to calculate the best
route according to the given criteria and save it as a specified S-57 SENC file.
The function EcRoutingCalculateOptimum is called with the following parameters:
• ro Pointer to routing object
• di Pointer to an object dictionary context
• startNode Name of start node
• endNode Name of end node
• viaNodes List of via node names
• nViaNodes Number of via nodes in list
• criterion Optimization criterion (EcRoutingDistance, EcRoutingSpeed)
• outputFileName Name of S-57 output SENC file
• progress Pointer to callback function
In the following example four possible return values are described.

108
 EC2007 ECDIS Kernel Programming Guide

The example calculates the shortest route from New York to Casablanca via the following via
nodes:
Via Node 1: “Boston – Rhode Island – New-York Approach”
Via Node 2: “BS1 / Norlant”
The calculated shortest route is converted into an S-57 SENC file named MYROUTE.7CB in the
directory C:\Routing\RouteObjects.
EcRouting *routing;
EcDictInfo *di;
EcRoutingNodeName startNode = "NEW YORK";
EcRoutingNodeName endNode = "CASABLANCA";
EcRoutingNodeName via[2];
char *OutputFile = "C:/Routing/RouteObjects/Routes.7CB";

via[0] ="BOSTON - RHODE ISLAND - NEW YORK APPROACH";

via[1] ="BS1/NORLANT";

int result = EcRoutingCalculateOptimum(routing, di, startNode, endNode,

via, 2, EcRoutingDistance, OutputFile, NULL);

There are four possible values for the variable result:

If the function returns 1 the best route is calculated and the result is converted into an S-57
SENC file.
If the function returns 0 calculating the best route is impossible. That means that there is no
connection from the start node to the end node via the via nodes.
The value -1 is returned in case the callback function progress monitors a user-defined
interrupt.
The function returns -2 in case an error has occurred or invalid parameter(s) were given.
For a complete example of how to extract a best route from the SevenCs Route Database
please refer to the example program getBestRoute.

7.6 Monitoring
The 'ECDIS Performance Standards' require not only to check the planned route prior to the
start of the voyage but also to check the vessel’s position in relation to the planned route,
and the surrounding dangers at any given time during the voyage:
"In order to safeguard against the risk of grounding, a position-monitoring system shall
enable detection of cross-track error in relation to the pre-planned route and release an
alarm at a time to danger of grounding which allows for proper and effective action to be
taken by the back-up officer" [Watch-1 Specification of Det Norske Veritas].
ECDIS can perform even more than anti-grounding, its motion prediction allows the mariner
to see where his vessel will be positioned within the next few minutes. This prediction (see
chapter Prediction) is not a simulation! It is simply the extrapolation of the actual motion

109
EC2007 ECDIS Kernel Programming Guide

parameters and therefore applicable for all types of vessels - from the smallest pilot launch
to the largest super tanker.

7.6.1 Activating a Waypoint

Once the route has been fully planned, selected, and checked the voyage can begin. During
the voyage the waypoint that is the next waypoint to be reached along the preferred route
should be highlighted in some way. For this purpose SevenCs has defined the attribute
‘active’, and added it to the object class ‘waypnt’. Value 1 indicates that the waypoint is
activated, and value 2 that it is not. The ECDIS Kernel provides a function to activate a special
waypoint of the preferred route. The function EcMonitorSetActiveWaypoint is used to set the
attribute ‘active’ of the specified waypoint object to 1. The parameters are:
• dictInfo Pointer to a dictionary context
• nextWp Handle of the waypoint feature object to be activated
This function returns False if an error has occurred, e.g. if the specified nextWp is not part of
a preferred route, and True on success.

Please note:
Only one waypoint of the entire preferred route can be activated. The function ensures
that only the specified waypoint is activated and all others are not.

To retrieve the distance and bearing of the own ship to the active waypoint the function
EcMonitorGetActiveWaypoint can be used. The parameters are:
• cellId Identifier of the mapped cell containing the route object
• dictInfo Pointer to a dictionary context
• datum Horizontal datum
• shipLat Latitude of the ship’s current position
• shipLon Longitude of the ship’s current position
• dist Distance to the activated waypoint
• course Course to the activated waypoint
The return value of this function is a handle to the activated waypoint which can be checked
for errors using the macro ECOK.

7.6.2 Cross Track Distance

The cross track distance or cross track error is defined as the orthogonal distance of the own
ship from the preferred route. This distance can be retrieved by means of the function
EcMonitorCalculateOffTrack. The parameters are:
• route Handle of route feature object
• dictInfo Pointer to a dictionary context

110
 EC2007 ECDIS Kernel Programming Guide

• datum Horizontal datum

• shipLat Latitude of the ship’s current position
• shipLon Longitude of the ship’s current position
• offTrack Deviation from the planned track in nautical miles
This function returns True on success and False otherwise.

Please note:
At waypoints it only calculates the distance from the straight legs.
The function searches for an activated waypoint and takes the leg line to this waypoint
for the calculations.

If the current cross track distance of the own ship is greater than the specified cross track
limit of the preferred route an alarm should be given. The cross track limit defines the
corridor around the leg of a route in which a vessel is considered to be on track. The value of
the cross track limit is stored in the attribute ‘xtrack’ of the legline feature object ‘leglin’. It
can be set by means of the function EcFeatureSetAttributes when creating a legline object.
The corridor around the legs of a route can be made visible with the function
EcChartSetShowCrossTrackLimits (see chapter Date Dependent Objects
A date or date range
Other Mariner’s Settings).

7.6.3 Anti-Grounding
As already mentioned above an ECDIS should provide a warning or alarm function to help
prevent the vessel from grounding or the collision with obstructions. To realize such a
warning function a so-called guard zone is defined in front of the path of the vessel. This
area will be checked for any objects that may be dangerous to the vessel.

[Link] The Guard Zone

The function EcMonitorDefineGuardZone is used to create a guard zone feature object. The
parameters are:
• cellId Identifier of an overlay cell
• dictInfo Pointer to a dictionary context
• numCoor Number of coordinate pairs of the guard zone area
• name Name of the guard zone (optional, may be NULL)
This function only creates a feature object for the guard zone, the actual geographic
location, i.e. the coordinates of the vertices can be specified by means of the function
EcMonitorMoveGuardZone. The parameter numCoor specifies the number of coordinate pairs
needed to define the guard zone area. This number has to be by one greater than the
number of vertices of the area, since the first coordinate must be identical to the last
coordinate. E.g. to define a guard zone with N vertices the number of coordinates is N+1.

111
EC2007 ECDIS Kernel Programming Guide

Please note:
The amount of coordinates must be at least 4 which makes a triangle the simplest guard
zone area possible.

The name that can be given is set in the objects attribute ‘OBJNAM’ and can be used to
distinguish the guard zone. The return value of this function is a handle to the created
feature object which can be checked for errors with the macro ECOK.
Before checking the guard zone for possible dangerous objects the geographic location must
be set. With the function EcMonitorMoveGuardZone the coordinates of the guard zone’s
vertices can be set. With this function the absolute coordinates of the vertices can be
specified, or the coordinates relative to a given position and course. The parameters are:
• guardzone Handle of guard zone feature object
• dictInfo Pointer to a dictionary context
• lat Latitude of reference position
• lon Longitude of reference position
• course Reference alignment in nautical degrees
• coords Array of guard zone coordinate pairs (lat/lon or distance/bearing)
• ncoords Number of coordinate pairs in coords array
• absolute Flag indicating absolute or relative coordinates
The handle of the guard zone feature object is returned by the function
EcMonitorDefineGuardZone when creating a guard zone. If the parameter absolute is set to
True the specified coordinates will be interpreted as absolute latitude and longitude values.
In this case the reference position lat and lon and the reference alignment course will be
ignored.
If the parameter absolute is set to False the coordinates will be interpreted as distance and
bearing from the given reference position and reference alignment, e.g. the current ship
position and course.
The following example shows how to create a triangular guard zone object and place it in
front of the own ship by using the current ship position and course as reference point.
#define NUMCOOR 8

EcCellId dynCid;
EcDictInfo *dictInfo;
EcFeature guardZone;
EcCoordinate shipLat, shipLon;
double shipCourse;
double angle = 20.0;
double dist = 1.5;
double coor[NUMCOOR];

/* the overlay cell for dynamic objects has been

created and mapped with EcChartOpenOverlayCell

112
 EC2007 ECDIS Kernel Programming Guide

// create a triangular guard zone object

guardZone = EcMonitorDefineGuardZone(dynCid, dictInfo, 4, NULL);
if (!ECOK(guardZone))
// guard zone object could not be created; error handling

// place the guard zone area in front of the ship

coor[0] = 0.0;
coor[1] = 0.0;
coor[2] = dist;
coor[3] = angle;
coor[4] = dist;
coor[5] = 360.0 - angle;
coor[6] = 0.0;
coor[7] = 0.0;

EcMonitorMoveGuardZone( guardZone, dictInfo, shipLat, shipLon,

shipCourse, coor, 4, False);

To check if any dangerous objects are inside the defined guard zone area the function
EcMonitorCheckGuardZone can be used. This function searches the guard zone area for
dangerous objects.
Apart from the danger dictionary context the function checking the guard zone area needs
the cells that are supposed to be checked. These cells can be loaded with the function
EcCellLoadByPolygon. However, this function has a linear execution time depending on the
number of vertices of the given polygon. Therefore it is not recommended to use the
function in case the guard zone area is defined by a vast amount of vertices.
To check for any dangerous objects within the guard zone the function
EcMonitorCheckGuardZone can be used. It takes the following parameters:
• guardzone Handle of guard zone feature object
• dictInfo Pointer to a dictionary context
• dngInfo Pointer to a danger dictionary context
• draught Value of safety depth in meters
• airdraught Value of safety height in meters
• level Warning level (EC_NOTE_LEVEL, EC_WARNING_LEVEL or EC_DANGER_LEVEL)
• cellIds Array of cell identifiers to check for dangers
• ncells Number of cell identifiers in cellIds array
• dngObj Pointer to array of dangerous feature objects found
The parameter dngInfo is a pointer to a danger dictionary context as returned by the
function EcQueryReadDangerDictionary (see chapter 7.3).
The level EC_NOTE_LEVEL will also return objects which are indicated as warning or danger.
The level EC_WARNING_LEVEL will also return objects which are indicated as danger.
The function EcMonitorCheckGuardZone stores all dangerous objects in an array of feature
objects. The memory needed for this array is allocated by the function and must be freed by

113
EC2007 ECDIS Kernel Programming Guide

the application using the function EcFree. The return value of this function is the number of
dangerous objects found during the check.
The following example shows how to retrieve the required cells using the function
EcCellLoadByArea and how to check the guard zone area using the function
EcMonitorCheckGuardZone.
#define MAX_CELLS 16
EcPrimitive prim;
EcPrimitiveType primType;
EcCoordinate minlat, minlon, maxlat, maxlon;
EcCellId cellIds[MAX_CELLS];
EcDangerInfo *dngInfo;
EcFeature *dngObjects;
EcFindInfo fi;
EcCatList *catList;
double safetyHeight, safetyDepth;
int numDngObj;
int numCells;

// create and position a guard zone object as described in the previous

example

// load the cells covering the guard zone polygon

numCells = EcCellLoadByPolygon(catList, coor, NUMCOOR, cellIds, MAX_CELLS);

// read the danger dictionary from the default path $LIB_7CS/lib/objcat

dngInfo = EcQueryReadDangerDictionary(dictInfo, "[Link]");

// check the guard zone area using the cells retrieved in the previous
example
numDngObj = EcMonitorCheckGuardZone(guardZone, dictInfo, dngInfo,
safetyDepth, safetyHeight, EC_NOTE_LEVEL,
cellIds, numCells, &dngObjects);

// indicate the danger objects by a list or highlight them

// unmap the cells covering the guardzone

for (i=0; i<numCells, i++)
EcCellUnmap(cellIds[i]);

// free danger dictionary

// usually this is done when the application is finished
EcQueryFreeDangerDictionary(dngInfo);

[Link] Display of Guard Zone

The guard zone has to be displayed by the application. This can be done by meaning of the
function EcDraw[NT|X11]DrawArea or by GUI tools.

114
 EC2007 ECDIS Kernel Programming Guide

7.6.4 Past Track

The EC2007 ECDIS Kernel provides functions to visualize the actual path of the vessel over
the ground during her voyage. This past track is realized as a feature object that is
continuously updated and redrawn while the ship is on the way.
To create a new past track feature object the function EcMonitorCreatePastTrack is used. The
parameters are:
• dynCellId Identifier of an overlay cell for dynamic objects
• dictInfo Pointer to a dictionary context
• name Name of the past track (optional, may be NULL)
It is highly recommended to create a dedicated overlay cell for the past track, because this
cell will be updated frequently and therefore has to be symbolized and drawn frequently as
well.
The created feature object is of the class ‘pastrk’ but does not yet hold any information
relevant to the current position of the ship. The past track feature object is related to two
primitives, a line primitive for the past track itself, and a cluster primitive for the time tags
on the track. The default maximum length of a past track object is 12 hours, however, this
length can be changed with the function EcMonitorSetPastTrackLength.
The ship relevant information can be set by means of the function EcMonitorSetPastTrack.
This function is used to append the current ship position, course, and speed to the past
track. The parameters are:
• pastTrack Handle of past track feature object
• dictInfo Pointer to a dictionary context
• lat Latitude of the ship’s position
• lon Longitude of the ship’s position
• time Time of position (in seconds since 1.1.1970 00:00 UTC)
• course Current course of the ship
• speed Current speed of the ship
This function determines whether the given parameters require a new vertex to be
appended to the existing edge of the past track or if a new edge must be created or an old
edge has to be removed. A point for a time tag is created if at least one minute has passed
since the last call.
The return value of this function reveals the actions that have been taken by this function
and can be used to determine whether the past track must be redrawn or symbolized. The
return values are:

115
EC2007 ECDIS Kernel Programming Guide

EC_PASTTRACK_NOCHANGE No changes were made.

EC_PASTTRACK_HASCHANGED Changes were made, e.g. a new vertex was appended to
the existing edge, but no symbolization is necessary.
EC_PASTTRACK_REQSYMB Major changes were made which require the
symbolization of the past track object, e.g. a new edge
was created or an old one removed or a time tag was
added.
The function EcMonitorSetPastTrackLength can be used to define the maximum length of the
past track in minutes. The parameters are:
• pastTrack Handle of past track feature object
• dictInfo Pointer to a dictionary context
• maxlen Maximum length of past track in minutes
The function EcMonitorSetPastTrack determines whether an old edge shall be removed from
the past track on the basis of this maximum length. If all vertices of an edge are older than
the maximum length the edge will be removed.
It is also possible to clear an existing past track to start recording the ship’s track anew. The
ECDIS Kernel function EcMonitorClearPastTrack removes all information stored in the given
past track object. However, the object proper is not deleted and can be used to set new ship
relevant information.
The function EcMonitorSetPastTrackData allows to attach textual information to the specified
time label on the past track. This is particularly useful for logging purposes. Data will be
attached to the closest matching time label.
Any textual information attached to the specified time label of the past track can be queried
with the function EcMonitorGetPastTrackData.
The function EcMonitorGetAllPastTrackData returns all textual information and the respective
time labels of the past track. This can be useful in case a log file must be created, or log
information shall be presented to the mariner.

7.6.5 Prediction
The prediction functionality of the ECDIS Kernel is used to determine the movement of the
ship when precise manoeuvring is required.
The function EcMonitorCalculatePrediction predicts the ship’s position in a specified time on
the basis of the current position, course, and speed. The parameters are:
• timediff Prediction time interval in seconds
• curlat Current latitude of the ship’s position
• curlon Current longitude of the ship’s position
• heading Current heading of the ship
• cmg Current course made good of the ship
• speed Current speed of the ship

116
 EC2007 ECDIS Kernel Programming Guide

• rateOfTurn Current rate of turn in degrees per minute

• predLat Predicted latitude of the ship’s position
• predLon Predicted longitude of the ship’s position
• predHeading Predicted heading of the ship
• rotLat Latitude of rotation center point
• rotLon Longitude of rotation center point
This function calculates the ship's position and heading from the parameters of the current
ship's movement. This algorithm is not a simulation of the ship's movement. If the
parameters change rapidly the predicted situation will change, too. It is not useful to specify
a time interval for the prediction greater than 60 seconds.

Please note:
The calculation is independent of e.g. the ship's length, breadth, deadweight etc..
Therefore the movement prediction can be calculated for every type of vessel.

7.7 Manual Updating

An ECDIS should not only support automatic updating of S-57 data as described above but
should also allow the data to be manually corrected. These changes must be visualized, and
may not restrict the possibility of automatic updating.
There are three ways to change objects by a manual update:
• inserting objects
• modifying objects
• deleting objects
In the ECDIS Kernel the modification of objects is limited to adding text information or
moving objects. The latter is implemented as deleting the object, and afterwards inserting a
copy. The ECDIS Kernel also provides functions to cancel or withdraw manual updates, and
to query objects which have been inserted by manual updates.
An example implementation is given in the sample program manualupd.

7.7.1 The Manual Update Cell

Changing the original chart content is prohibited. Therefore new objects, marks for deleted
objects and annotations will be placed in a manual update cell, the so-called ghost cell. This
cell is created automatically and will be evaluated during the visualization process. The ghost
cell is automatically mapped and assigned to the view. The view structure manages the
access to the ghost cell. The cell should not be assigned to any other views.
There are special functions to access these ghost cells. All functions that modify a ghost cell
automatically invalidate the corresponding Display List. Consequently the symbolization
using the function EcChartSymbolizeView creates a new Display List. In some cases it might be
117
EC2007 ECDIS Kernel Programming Guide

sufficient to symbolize only the changed object. However, this is difficult to assess by the
application developer.

7.7.2 The Manual Update List

Objects which can be created and inserted by a manual update are defined in a Manual
Update List. Each entry in this list contains the definition of an object or a combination of
objects (e.g. a buoy with topmark and light) and can be addressed with an index. The ECDIS
Kernel provides predefined entries, which are created automatically when creating the
Manual Update List. The list can then be enhanced by adding user-defined entries. The
predefined entries cannot be changed.
Each entry contains a text field describing the object. This text is intended to be used in a
menu or selection list of the user interface. It is also possible to display the visualization of
each entry in order to realize the selection in form of symbols instead of text.
The Manual Update List is created with the function EcManualUpdateListCreate. This function
has no parameters and returns a pointer to a structure of type EcManualUpdateList. The
definition of this structure is not visible to the user of the ECDIS Kernel. All functions using
the Manual Update List receive the pointer returned by the function
EcManualUpdateListCreate as a parameter. When creating the Manual Update List the
function allocates memory for the list structure. If the list is no longer needed the memory
should be freed by the application using the function EcManualUpdateListFree.
The number of entries in the Manual Update List can be obtained with the function
EcManualUpdateListGetSize. The parameters are:
• maul Pointer to a Manual Update List of type EcManualUpdateList as returned by
the function EcManualUpdateListCreate
• pType Pointer to a variable of type EcPrimitiveType (may be NULL)
Both the entire amount of entries and the number of entries of a specific geometry primitive
type can be queried, as illustrated in the following example.
EcPrimitiveType pT;
int n;
EcManualUpdateList *maul;

maul = EcManualUpdateListCreate();
// All entries
n = EcManualUpdateListGetSize(maul, NULL);
printf("%d entries in manual update list\n", n);
// Entries for point objects
pT = EC_P_PRIM;
n = EcManualUpdateListGetSize(maul, &pT);
printf("\t%d entries of type point\n", n);
// Entries for line objects
pT = EC_L_PRIM;
n = EcManualUpdateListGetSize(maul, &pT);
printf("\t%d entries of type line\n", n);
// Entries for area objects
pT = EC_A_PRIM;

118
 EC2007 ECDIS Kernel Programming Guide

n = EcManualUpdateListGetSize(maul, &pT);
printf("\t%d entries of type area\n", n);

The text description and the primitive type can be obtained for each entry using the function
EcManualUpdateListGetInfo. The parameters are:
• maul Pointer to a Manual Update List of type EcManualUpdateList
• idx Index of list entry 0 <= idx < n, where n is returned by
EcManualUpdateListGetSize(..,NULL)
• pType Pointer to a variable of type EcPrimitiveType (may be NULL)
• buffer Buffer for description of entry provided by the caller (may be NULL)
• bufsize Size of buffer
The following two figures show the predefined entries of the Manual Update List.

Figure 10: Manual Update List (Points)

119
EC2007 ECDIS Kernel Programming Guide

Figure 11: Manual Update List (Areas)

[Link] Adding Objects to List

If the Manual Update List with its predefined entries does not include all objects needed for
your purposes the list can be enhanced in the application. In this very unlikely case, new
entries can be inserted using the function EcManualUpdateListAddEntry and, if required,
modified afterwards with the function EcManualUpdateListExtendEntry.
The following example shows the enhancement of the Manual Update List by two entries, a
building with a flag pole and a telephone cable.
EcManualUpdateList *maul;
int idx;

maul = EcManualUpdateListCreate;
idx = EcManualUpdateListAddEntry(maul, "Building with flag pole",
EC_P_PRIM,
"BUISGL", "CONVIS1|", '|');
EcManualUpdateListExtendEntry(maul, idx, "LNDMRK",
"CATLMK5|CONVIS1|", '|');
idx = EcManualUpdateListAddEntry(maul, "Telephone cable", EC_L_PRIM,
"CBLSUB", "CATCBL4|", '|');

Only entries which have been inserted with the function EcManualUpdateListAddEntry can be
modified using the function EcManualUpdateListExtendEntry. Furthermore, it is only possible
to modify entries of the primitive type EC_P_PRIM.
If an entry consists of a combination of objects the first object serves as the master object
when inserting this entry into the SENC as a manual update. Therefore this object must be
defined using the function EcManualUpdateListAddEntry. In the example the object of class

120
 EC2007 ECDIS Kernel Programming Guide

BUISGL (single building) is the master object, the object of class LNDMRK (land mark) is a
slave object. In one single entry up to three slave objects can be defined.
The function EcManualUpdateDraw[X11|NT]Symbol is used to draw the symbol for the given
entry of the manual update object list into a device context. It can be used to build menus or
dialog elements for manual updating. This function uses the lookup table currently loaded in
the given view.
We recommend to load the "full chart lookup table", otherwise the same symbol will be
used for more than one entry.
The pivot point of the symbol will be centered in the specified area. In case the entry
represents an area object the object will be drawn using the whole area (10 % margin).
Before an entry of the Manual Update List can be drawn the function
EcManualUpdateDraw[X11|NT]Init must be called to initialize drawing and create a pointer to
a drawing context of type EcManualUpdateDrawContext. This drawing context is needed by
the function EcManualUpdateDraw[X11|NT]Symbol. After the drawing of symbols has been
completed the function EcManualUpdateDrawEnd should be called to free the memory
allocated to the drawing context.

7.7.3 Creating Objects

With the function EcManualUpdateAddObject an object or a combination of objects according
to an entry in the Manual Update List can be inserted into the ghost cell. The access to this
cell is encapsulated in the function so that the original S-57 cell is passed to the function. The
symbolization of the ghost cell is also realized internally when the original S-57 cell is
symbolized. The parameters of this function are:
• dictInfo pointer to dictionary context
• cid cell id of ghost cell (needs write access)
• maul pointer to an object list for manual update returned by
EcManualUpdateListCreate
• idx index of object list
• coor array of coordinate pairs (lat1, lon1,
• nCoor number of coordinate pairs in array
• updTime time of manual update (in seconds since 1
• comment text to be associated with the new object, will be stored in attribute INFORM

Please note:
The first and last coordinate pairs must be equal when inserting an entry of the Manual
Update List describing an area.

121
EC2007 ECDIS Kernel Programming Guide

7.7.4 Deleting Objects

To delete an object in
terms of a manual update the function
EcManualUpdateAddRemovalIndicator can be used.
The parameters of this functions are:
• dictInfo pointer to dictionary context
• ghostCellId cell id of ghost cell (needs write access)
• feature handle of feature object of original cell to be marked as removed
(needs read access to original cell)
• updTime time of manual update (in seconds since 1.1.1970)
• comment text to be associated with the new object, will be stored in attribute
INFORM
This function adds a removal indicator to the ghost cell at the position of the original feature.

7.7.5 Moving Objects

In case an object shall be moved in terms of a manual update the function
EcManualUpdateAddMoveIndicator can be used.
The parameters of this functions are:
• dictInfo pointer to dictionary context
• ghostCellId cell id of ghost cell (needs write access)
• feature handle of feature object of original cell to be marked as removed
(needs read access to original cell)
• updTime time of manual update (in seconds since 1.1.1970)
• comment text to be associated with the new object, will be stored in attribute
INFORM
This function adds a removal indicator to the ghost cell at the position of the original feature
and creates a new object of the same type at the new position.

7.7.6 Creating Annotations

To add an manual update annotation the function EcManualUpdateAddAnnotation can be
used.
The parameters of this functions are:
• dictInfo pointer to dictionary context
• ghostCellId cell id of ghost cell (needs write access)
• feature handle of feature object of original cell to be marked as removed
(needs read access to original cell)

122
 EC2007 ECDIS Kernel Programming Guide

• updTime time of manual update (in seconds since 1.1.1970)

• comment text to be associated with the new object, will be stored in attribute
INFORM
This function adds an annotation marker to the ghost cell at the position of the original
feature.

7.7.7 Modifying Objects

The objects in the ghost cell can be modified by the general functions for object or feature
editing (see Modifying Objects).

7.7.8 Withdrawing Manual Updates

Manual updates of all kind
can be withdrawed with the function
EcManualUpdateWithdrawUpdateAction. The parameters are:
• dictInfo pointer to dictionary context
• ghostCellId cell id of ghost cell (needs write access)
• actionId id of a manual update action
This function removes the manual update marker or object with the given action Id from the
ghost cell.

7.7.9 Querying Manual Updates

Objects or markers which have been created in the ghost cell cannot be queried by the
function EcQueryPickVisible. Instead the functions EcManualUpdatePick or
EcManualUpdateSpot must be used. The first one is used to query for the objects at a specific
position. With the second one it can be queried for all objects within the ghost cell.
The parameters of EcManualUpdatePick are:
• view Pointer to a view context
• pickX X coordinate of pick position (screen coordinates)
• pickY Y coordinate of pick position (screen coordinates)
• pickRadius Pick radius in pixels
• features List of features found
The parameters for EcManualUpdateSpot are:
• view Pointer to a view context
• cid Cell assigned to view
• features List of features found

123
EC2007 ECDIS Kernel Programming Guide

7.7.10 Displaying Manual Updates

If a SENC file has a corresponding manual update cell will be symbolized and draw
automatically. There
In case manual updates which have been created within a certain date range shall only be
displayed the function EcChartSetManualUpdateDateRange has to be used.

7.8 Navigational Calculations

For navigational calculations the following functions are used:
EcCalculateRhumblineDistanceAndBearing calculates loxodromic distance and bearing.
EcCalculateRhumblinePosition calculates a position on a rhumbline.
EcCalculateGreatCircleDistanceAndBearing calculates geodesic distance and bearing.
EcCalculateGreatCirclePosition calculates a position on a geodesic.
These functions implement the algorithms of Vincenty which give a distance accuracy of
better than one millimeter for all ranges. All calculations are performed on the spheroidal
earth.

7.9 Sensor Data

In most cases application builders have their own sensor data handling implemented.
However, the EC2007 ECDIS Kernel supports some basic sensor handling, based on the
NMEA telegrams.

7.9.1 Introduction
The EC2007 ECDIS Kernel includes functions to handle navigational sensor data in the IEC
61162-1 standard format, which is derived from the NMEA 0183 format specification. An
ECDIS needs to be connected to navigational sensors to be able to fulfill the requirement of
displaying the current ship’s position on the chart. Additionally, the ship’s heading and speed
over ground are needed to display a ship symbol. It may also be desired for an ECDIS to
record the received sensor data to realize black box functionality.
The IEC 61162-1 standard specifies the electrical connection between two navigational
devices as well as the data transmission format. An RS-422 interface is required for the
electric connection. However, for compatibility reasons the RS-232 interface should also be
connectable. Both the RS-422 and the RS-232 are serial interfaces which need to run with
the following parameters:
• 4800 Baud
• 8 data bits, no parity bit
• 1 stop bit

124
 EC2007 ECDIS Kernel Programming Guide

A complete description of the telegrams supported by the EC2007 ECDIS Kernel is given in
the following section.

7.9.2 NMEA Data Reading

The initialization of the interface has to be implemented by the application builder. There
are different initialization functions for the Windows NT and LINUX operating systems. These
functions return a file handle or a file descriptor which can be used to read data,
respectively. An application should use select to wait for data to be available, and read to
obtain the data.
Once the interface has been initialized, the function EcSensorReadNmea can be used to parse
this message and store its values in a structure. The parameters of this function are:
• msg String containing the data telegram
• nmea Union of type EcNmea in which the message is stored
The function returns True on success and False on failure. In case of an error the union nmea
is an EcERROR_type structure with the following data fields:
int msgType;
int status;

The status field gives more details about the error that has occurred. Possible values are:
EC_ERROR_CHECKSUM // invalid checksum detected
EC_ERROR_INVAL // no telegram specified
EC_ERROR_FATAL // cannot allocate memory
EC_ERROR_MISS_FIELD // unexpected end of telegram
EC_ERROR_PROP // proprietary sentences are unsupported
EC_ERROR_QUEST // query sentences are unsupported
EC_ERROR_FORMAT // value of unexpected type detected
EC_ERROR_UNKNOWN_MSG // type of given sentence is unsupported
EC_ERROR_NOTERM // telegram delimiter not found

The union EcNmea, depending on the message type, is made up of one of the following
members:
typedef union
{
int msgType;
EcDBT_type DBT;
EcDPT_type DPT;
EcDTM_type DTM;
EcGGA_type GGA;
EcGLL_type GLL;
EcHDT_type HDT;
EcHDG_type HDG;
EcMWV_type MWV;
EcOSD_type OSD;
EcRMC_type RMC;
EcROT_type ROT;

125
EC2007 ECDIS Kernel Programming Guide

EcRPM_type RPM;
EcRSA_type RSA;
EcSNU_type SNU;
EcTLL_type TLL;
EcTTM_type TTM;
EcVBW_type VBW;
EcVHW_type VHW;
EcVTG_type VTG;
EcZDA_type ZDA;
EcERROR_type Error;
}EcNmea;

These structures consist of different data fields for the different values of the message.
However, the following data fields are contained in the structure for all message types:
• msgType Define for the message type (see below)
• timestamp Time when the message was parsed
• available Bit mask indicating which data fields of the telegram are filled
• talker Define for the device type (see below)
The defines for the parameter msgType are:
EC_MSG_UNKNOWN
EC_MSG_ERROR
EC_MSG_DBT
EC_MSG_DPT
EC_MSG_DTM
EC_MSG_GGA
EC_MSG_GLL
EC_MSG_HDT
EC_MSG_HDG
EC_MSG_MWV
EC_MSG_OSD
EC_MSG_RMC
EC_MSG_ROT
EC_MSG_SNU
EC_MSG_TLL
EC_MSG_TTM
EC_MSG_VBW
EC_MSG_VHW
EC_MSG_VTG
EC_MSG_ZDA

The defines for the parameter talker are:

EC_SENSOR_UNKNOWN
EC_SENSOR_AUTOPILOT_GENERAL // AG
EC_SENSOR_AUTOPILOT_MAGNETIC // AP
EC_SENSOR_COMM_DSC // CD
EC_SENSOR_COMM_DATARECEIVER // CR
EC_SENSOR_COMM_SATELLITE // CS
EC_SENSOR_COMM_TELEPHONE_MF_HF // CT

126
 EC2007 ECDIS Kernel Programming Guide

EC_SENSOR_COMM_TELEPHONE_VHF // CV
EC_SENSOR_COMM_SCANNINGRECEIVER // CX
EC_SENSOR_DECCA // DE
EC_SENSOR_DIRECTIONFINDER // DF
EC_SENSOR_ECDIS // EC
EC_SENSOR_EPIRB // EP
EC_SENSOR_ENGINEROOM_SYSTEMS // ER
EC_SENSOR_GPS // GP
EC_SENSOR_MAGNETIC_COMPASS // HC
EC_SENSOR_GYRO_NORTHSEEKING // HE
EC_SENSOR_GYRO_NON_NORTHSEEKING // HN
EC_SENSOR_INT_INSTRUMENTS // II
EC_SENSOR_INT_NAVIGATION // IN
EC_SENSOR_LORAN_A // LA
EC_SENSOR_LORAN_C // LC
EC_SENSOR_OMEGA // OM
EC_SENSOR_RADAR // RA
EC_SENSOR_SOUNDER_DEPTH // SD
EC_SENSOR_POSITIONINGSYSTEM // SN
EC_SENSOR_SOUNDER_SCANNING // SS
EC_SENSOR_TURNRATE_INDICATOR // TI
EC_SENSOR_TRANSIT // TR
EC_SENSOR_LOG_DOPPLER // VD
EC_SENSOR_LOG_MAGNETIC // VM
EC_SENSOR_LOG_MECHANIC // VW
EC_SENSOR_WEATHER_INSTRUMENTS // WI
EC_SENSOR_TRANSDUCER // YX
EC_SENSOR_ATOMIC_CLOCK // ZA
EC_SENSOR_CHRONOMETER // ZC
EC_SENSOR_QUARTZ_CLOCK // ZQ
EC_SENSOR_RADIO_UPDATED_CLOCK // ZV
EC_SENSOR_PROPRIETARY_CODE // P
EC_SENSOR_DGPS

Please note:
Since the IEC 1162-1 standard allows message fields to contain no data the member
available should always be evaluated before accessing the data stored in the structure.
A list of the NMEA structures of the individual message types is given in the Annex A.

7.9.3 NMEA Data Registering

It is, however, also possible to register specific message types for a serial line in order to
implement that only these types of messages shall be parsed, and all others shall be ignored.
The function EcSensor[X11|NT]AddTelegram is used to register message types. The
parameters are:
• filehandle File handle/descriptor for which the message type is registered
• telegram Three-character code identifying the message type
127
EC2007 ECDIS Kernel Programming Guide

The file handle is the return value of the function EcSensor[X11|NT]InitNmea. The three-
character codes for the message types are defined in the IEC 61162-1 standard. The message
types currently supported by the EC2007 ECDIS Kernel are:
• DBT Depth Below Transducer
• DPT Depth
• DTM Geographic Datum in use
• GGA Global Positioning System Fix Data
• GLL Geographic Position
• HDT Heading (True)
• HDG Heading, Deviation and Variation
• MWV Wind Speed and Angle
• OSD Own Ship Data
• RMC Recommended Minimum Specific GPS/TRANSIT Data
• ROT Rate of Turn
• RPM Revolutions
• RSA Rudder Sensor Angle
• SNU Signal to Noise Ratio
• TLL Targets Geographic Position
• TTM Tracked Target Message
• VBW Dual Ground / Water Speed
• VHW Water Speed and Heading
• VTG Course Over Ground and Ground Speed
• ZDA Time and Date
It is possible to register more than one message type for a particular serial line, which is
identified by its file handle/descriptor.

Please note:
A list of the NMEA structures of the individual message types is given in the Annex A.

To check if a message that has been read is of a registered type the message type (three-
character code) must be taken from the read message. With this message type the function
EcSensor[X11|NT]CheckTelegram can be called. The parameters are:
• filehandle File handle/descriptor for which the message type registration is checked
• telegram Three-character code identifying the message type
This function returns True if the specified message type is registered and False otherwise.

128
 EC2007 ECDIS Kernel Programming Guide

The following example (for UNIX) describes the steps necessary to implement parsing of
messages of type GGA and VTG. The serial line is opened and initialized, the message types
GGA and VTG are registered for that line, the messages are read, and only the GGA and VTG
type messages are parsed.
char *devName = "/dev/cua1";
int fd;
FILE *deviceFile = NULL;
EcNmea nmeaStruct;

/* open "/dev/cua1" and set following parameters: */

/* 4800 Baud, 8 data bits, no parity, 1 stop bit */
fd = EcSensorX11InitNMEA( devName);
if( fd < 0 )
{
fprintf( stderr, "Cannot open device: %s\n", devName);
return -1;
}

/* register the GGA and VTG telegram */

if( (!EcSensorX11AddTelegram( fd, "GGA")) || (!EcSensorX11AddTelegram( fd,
"VTG")) )
{
fprintf( stderr, "Cannot register telegram\n");
close( fd );
return -1; }

deviceFile = fdopen( fd, "r");

if( !deviceFile )
{
fprintf( stderr, "Cannot associate file descriptor to stream\n");
close( fd );
return -1;
}

/* parse incoming NMEA telegrams */

while( fgets( buffer, sizeof(buffer), deviceFile) )
{
/* check if this telegram is registered */
/* the message type is located at the fourth character position */
if( EcSensorX11CheckTelegram( fd, buffer+3) )
{
EcSensorReadNmea( buffer, &nmeaStruct);
switch( [Link] )
{
case EC_MSG_GGA:
ProcessGGA( &nmeaStruct );
break;
case EC_MSG_VTG:
ProcessVTG( &nmeaStruct );
break;
case EC_MSG_ERROR:

129
EC2007 ECDIS Kernel Programming Guide

fprintf( stderr, "Invalid Telegram: %s\n", buffer);

break;
default:
fprintf( stderr, "Unexpected message type\n");
fclose( deviceFile );
return –1;
break;
}/*switch*/
}/*if*/
}/*while*/
fclose( deviceFile );

The registration of message types for a particular serial line can also be handled during
runtime of the ECDIS application. With the functions EcSensor[X11|NT]AddTelegram and
EcSensor[X11|NT]RemoveTelegram the list of registered message types can be modified. To
retrieve this list of registered types as a whole the function EcSensor[X11|NT]GetTelegrams
can be used.
The function EcSensor[X11|NT]RemoveTelegram is used to delete a message type from the list
of registered message types. The parameters are:
• filehandle File handle/descriptor for which the
• message type is registered.
• telegram Three-character code identifying the
• message type to be removed.
This function returns True on success and False otherwise.
The function EcSensor[X11|NT]GetTelegrams is used to retrieve the list of registered message
types. The parameters are:
• filehandle File handle/descriptor
• telegrams Pointer to a buffer containing the list of registered message types
The file handle specifies the serial line for which the list is to be retrieved. The memory
needed for the return parameter telegrams is allocated by the function and must be freed by
the application using EcFree. The return value of this function indicates the number of
registered message types.

7.9.4 NMEA Data Recording

When sensor data are processed by the function EcSensorReadNmea it is possible to write
these data into a log file. This requires at least one file handle to have been registered as a
log file. The registration can be done with the function EcRecordStartSensorDataLog. This
function takes a file handle as only parameter. In case this function is called more than once
with different file handles the function EcSensorReadNmea writes the processed sensor data
into all registered log files.

130
 EC2007 ECDIS Kernel Programming Guide

To stop recording the sensor data the registered file handle must be unregistered with the
function EcRecordStopSensorDataLog which also takes a file handle as only parameter. It is
necessary to call this function before the log file is closed.
In order to add supplementary user data to the log file the function EcRecordWriteUserData
can be used. This function writes the given string containing the user data to the specified
file handle.

7.10 Radar

7.10.1 Radar Overlay

The EC2007 ECDIS Kernel does not provide any Radar Hardware related functions, i.e. there
are no functions which interface with the Radar or Radar applications.
However the EC2007 ECDIS Kernel provides the function EcDraw[X11|NT]DrawRadar with
which the contents of the chart picture can be split into an over-radar and an under-radar
part. With the use of this function it is possible to merge a radar image into the chart
picture. The S-52 Presentation Library specifies which contents belong to the over- and
under-radar part.

7.10.2 Display of radar (ARPA) targets

Radar targets can be displayed either by means of the GUI toolkit or by means of the EC2007
ECDIS Kernel’s internal approach of storing the radar targets in an overlay cell (see chapter
Overlay Cells). For this the object class radtar has to be used. For a detailed list of additional
possible attributes please refer to the document EC2007_BackgroundInformation.

Please Note:
The requested flashing of radar target symbols in IEC 62288 is not supported by the
EC2007 ECDIS Kernel.

7.11 AIS
It has long been realized that an automatic reporting device (transponder) fitted to a ship
would be beneficial to the safety of navigation and the control and monitoring of the
maritime environment. With the advent of GPS and DGPS and modern data communication
it has become feasible and moderately cheap to provide such system.
An automatic reporting system has been developed for the maritime industry using the
maritime VHF band for the transmission and reception of its data signals, and has been
defined as a Universal Identification System (Universal AIS).
In combination with an Electronic Chart Display and Information System (ECDIS) the AIS
system brings a real benefit to a mariner on board of a ship. The latest position information

131
EC2007 ECDIS Kernel Programming Guide

of all vessels within range of the AIS can be displayed on a computer screen to prevent
accidents on sea.

7.11.1 The AIS Interface Library

Within the EC2007 ECDIS Kernel the AIS Interface Library is separated from the Kernel
Library and provided as a so-called Driver Programming Interface (DPI). The library
[Link] for Windows OS is located in the directory $EC2007DIR\lib\AIS\lib, the header file
dpimaist.h in $EC2007DIR\lib\AIS\include. Under Linux OS the library [Link] is
located in /usr/lib and the header file dpimaist.h in /usr/include.

Please note:
The display of AIS targets is independent of the AIS Interface Library and must be
implemented separately, either by using the drawing functions of the GUI toolkit or by
using the approach of overlay cells of the EC2007 ECDIS Kernel (see chapter Overlay Cells).

An example of the AIS handling and display is given in the sample program showAIS.
The following flowchart shows how the module is interfaced with an electronic chart display
system.

132
 EC2007 ECDIS Kernel Programming Guide

Figure 12: AIS Interface

The application reads data from the serial RS-232 interface to which the AIS transponder is
connected. These raw bytes are sent to the AIS module which calls the hardware driver (DPI)
to evaluate the received data. After the driver has returned the result of the evaluation to
the API the AIS module processes this information and passes it on to the application which
is now able to display on the screen AIS targets and messages, both addressed and
broadcast.
The following AIS message types are supported:

Message Description
1,2,3 Position report
4 Base station report
5 Ship static and voyage related data
6 Binary addressed message

133
EC2007 ECDIS Kernel Programming Guide

7 Binary acknowledge
8 Binary broadcast message
9 Standard SAR aircraft position report
10 UTC and date inquiry
11 UTC and date response
12 Addressed safety related message
13 Safety related acknowledge
14 Safety related broadcast
18 Standard Class B equipment position report
19 Extended Class B equipment position report
21 Aids-to-navigation position report
24 Static data report (Part A/Part B)

7.11.2 Transponder Connection

Before any AIS telegrams can be read an AIS transponder object has to be created with the
function EcAISNewTransponder. Usually this is done once during the start of the application.
The parameters are:
• transponder Reference to a pointer of an EcAISTransponder object
• moduleFileName File name of module to use as parser for the transponder's messages
• type Select internal/external GPS usage
The parameter moduleFileName defines the file name of the DPI, usually [Link]. It is
associated with the newly created EcAISTransponder object, and then used to parse the
bytestream that is read from the transponder hardware. In this case TRUE is returned.
Otherwise FALSE is returned and a NULL value is assigned to *transponder. The returned
pointer must be released with EcAISDeleteTransponder.
To fill the AIS transponder object with the AIS telegrams received via the serial interface the
function EcAISAddTransponderOutput is used. The parameters are:
• transponder Pointer to an EcAISTransponder object
• byteStream Byte stream that has been read from the serial interface to a
transponder
• len Length of the byte stream
This function must be called to process data that have been read from the transponder
hardware. After a specific amount of bytes has been received the parser of the DPI is called
internally, and the message queue and AIS target list are updated. If the bytestream has
been stored successfully in the internal queue TRUE will be returned, FALSE otherwise.
To remove an AIS target from the internal list, the function EcAISRemoveTarget must be used.
The parameters are:

134
 EC2007 ECDIS Kernel Programming Guide

• transponder Pointer to an EcAISTransponder object

• mmsi MMSI number of the target to be deleted from the internal list

Please note:
If a target is ‘lost’ the application is in charge of deleting it.

7.11.3 AIS Callback

The callback function which is invoked by any change of a target info structure in the
transponder object can be set using the ECDIS Kernel function EcAISSetTargetUpdateCallBack.
The parameters are:
• transponder Pointer to AIS transponder
• callback Pointer to callback function
The parameter for callback function itself is a pointer to the internal AIS target info structure
EcAISTargetInfo.

7.11.4 AIS Target Information

All information of the individual AIS targets are stored in a EcAISTargetInfo structure which
is internally passed to the callback function. The members of this structure can be used to
filter for AIS targets which shall be diplayed.

Bool ownShip Flag indicating if target is from own or other

ship.
EC_AIS_INVALID_MMSI indicates invalidity.
unsigned int mmsi The MMSI number of the AIS target the
information belongs to.
EC_AIS_INVALID_MMSI indicates invalidity.
unsigned char aisVersion AIS version indicator 0=ITU-R M.1371-1, 1=ITU-
R M.1371-3.
EC_AIS_INVALID_MMSI indicates invalidity.
EcAISNavStatus navStatus The navigational status of the AIS target.
int rot Rate of turn [1/10 °/min];
Values range from -720 to +720 °/min.
EC_AIS_INVALID_ROT indicates “not available”.
unsigned short sog Speed over ground [1/10 kts]. Value represents
steps of 1/10 kts ranging from 0.0 to 102.4 kn.
EC_AIS_INVALID_SOG indicates “not available”.
EcAISPosAccuracy posAccuracy The accuracy of the position report.
int longitude Longitude of AIS target [1/10000 min],
>=0: East, <0: West.

135
EC2007 ECDIS Kernel Programming Guide

EC_AIS_INVALID_LAT indicates “not available”.

int latitude Latitude of AIS target [1/10000 min],
>=0: North, <0: South.
EC_AIS_INVALID_LON indicates “not available”.
unsigned short cog Course over Ground [1/10 °]. Value represents
steps of 1/10° ranging from 0° to 359.9°.
EC_AIS_INVALID_COG indicates “not available”.
unsigned short heading Heading.
Value represents steps of 1° ranging from 0° to
359°.
EC_AIS_INVALID_HEADING indicates “not
available”.
unsigned int imoNumber The IMO number of the vessel.
EC_AIS_INVALID_IMO indicates invalidity.
char callSign[EC_AIS_CALL_SIGN_LEN] The call sign of the vessel. A string of length
zero indicates “not available”.
char vendorID[EC_AIS_CALL_SIGN_LEN] Vendor ID parsed in message 24.
char The ship's name. A string of length zero
shipName[EC_AIS_SHIP_NAME_LEN] indicates “not available”.
unsigned char shipType Type of ship.
EC_AIS_INVALID_SHIP_TYPE indicates
invalidity.
EcAISAntennaPos antennaPosition Position of the antenna relative to the ships
outline.
EcAISNavSensorType navSensorType Indicates type of navigational sensor.
EcAISNavSensorStatus navSensorStatus Indicates status of navigational sensor.
EcAISActivationStatus activationStatus Indicates activation status.
EcAISTrackingStatus trackingStatus Indicates tracking status.
char Name of Aids-to-navigation. Only in message
navName[EC_AIS_NAV_NAME_LEN] 21.
EcAISEta eta Represents estimated time of arrival.
unsigned char actualDraught Actual draught [1/10 m]; Ranges from 0.0 m to
25.4 m.
EC_AIS_INVALID_ACT_DR indicates “not
available”.
unsigned int altitude Actual altitude in metres. Only in message 9.
char Name of destination port. A string of length
destination[EC_AIS_DESTINATION_LEN] zero indicates “not available”.
EcAISTime lastSysTimeOfReport System time when last position telegram was
received.

136
 EC2007 ECDIS Kernel Programming Guide

time_t parseTime Time the message was parsed. Number of

seconds elapsed since midnight (00:00:00),
January 1, 1970; Coordinated Universal Time
(UTC), according to the system clock.
unsigned char utcTimeStamp UTC second when the report was generated (0
... 59).
EC_AIS_INVALID_UTC_TS indicates “not
available”.
EC_AIS_DEAD_RECKONING_MODE indicates
dead reckoning mode.
EC_AIS_MANUAL_MODE indicates inoperative
or manual input mode of positioning system.
EcAISTime lastUtcTimeFromTarget Last UTC time received from the AIS target.

[Link] Enumerated Types and Type Definitions

This section describes the enumerations and data types used in the EcAISTargetInfo
structure.

EcAISNavStatus
Navigational Status of an AIS target, transmitted by the transponder. Values defined as
follows:

eNavS_undefined Undefined navigation status.

eNavS_underWay Ship is under way.
eNavS_atAnchor Ship is at anchor.
eNavS_notUnderCommand Ship is not under command.
eNavS_restrManoeuvr Ship has restricted manoeuvrability.
eNavS_draughtConstrained Constrained manoeuvrability due to draft.
eNavS_moored Ship is moored.
eNavS_aground Ship is aground.
eNavS_fishing Ship is fishing.
eNavS_sailing Ship is sailing.
eNavS_emergency Ship is in a state of emergency.
eNavS_baseStation Indicates a base station.

EcAISTrackingStatus
Tracking Status of an AIS target, defined by the application. Values defined as follows:

aisTracking_undefined
aisInformationAvailable

137
EC2007 ECDIS Kernel Programming Guide

aisIntruder AIS targets nearer than the warning distance

aisDangerous AIS target (activated or not) which data contravene pre-set
CPA and/or TCPA limits
aisLost AIS target with last valid position before the reception of its
data was lost.

EcAISActivationStatus
Activation Status of an AIS target, defined by the application. Values defined as follows. For a
description of the values please refer to chapter

aisActive_undefined
aisSleeping sleeping AIS targt
aisActivated activated AIS target
aisActivatedPasttrack n/a
aisActivatedHeading activated AIS target with SOG and heading indication
aisActivatedPasttrackHeading n/a
aisSelected selected AIS target
aisSelectedPasttrack n/a
aisSelectedHeading selected AIS target with SOG and heading indication
aisSelectedPasttrackHeading n/a
aisSleepingVector sleeping AIS targt with SOG indication

EcGPSType
Enumeration to select internal/external GPS usage.

EcGPSt_undefined Undefined GPS usage.

EcGPSt_externalGPS Use external GPS.
EcGPSt_internalGPS Use internal GPS.

EcAISMessageType
Enumeration to identify the type of a message. Values defined as follows:

eMsgT_undefined Undefined message type.

eMsgT_unknown Message is of unknown type and must be evaluated by the
user.
eMsgT_addressed The message has been received / is to be sent as addressed,
i.e. it was sent by an AIS target / an AIS equipped vessel
specified by its MMSI number to a destination specified by
another MMSI number.
eMsgT_broadcast The message has been received / is to be sent as broadcast,

138
 EC2007 ECDIS Kernel Programming Guide

i.e. that a broadcast message has been received / that all

AIS targets within range will receive this message.
eMsgT_acknowledgement The message is an acknowledgement for a previously
received message.
eMsgT_noMessage There was no message in the queue.

EcAISPosAccuracy
Accuracy of reported position. Values defined as follows:

ePosA_undefined Indicates that position accuracy is not available.

ePosA_high Accuracy <10m due to usage of DGNSS receiver.
ePosA_low Accuracy >10m due to autonomous mode of GNSS receiver.

EcAISNavSensorType
Indicates the type of navigational sensor:
eNSTy_undefined
eNSTy_gps
eNSTy_glonass
eNSTy_combGpsGlonass
eNSTy_loranC
eNSTy_chayka
eNSTy_integratedNavSystems
eNSTy_surveyed
eNSTy_other

EcAISNavSensorStatus
Indicates the status of navigational sensor:
posSensor_undefined
posSensor_operating
posSensor_manual
posSensor_deadReckoning
posSensor_inoperative

[Link] Structured Types

This section describes the structured data types used.

EcAISMessage
Structure to hold type of message and message text/contents.

EcAISMessageType type The type of message that has been received / is to be

139
EC2007 ECDIS Kernel Programming Guide

sent.
unsigned int mmsiSrc The MMSI number that belongs to the sender of the
message.
unsigned int mmsiDst The MMSI number that belongs to the recipient of
the message.
unsigned char The contents of the message.
msg[MESSAGE_LEN]
unsigned int len Length of the “msg” array.

EcAISTime
Universal Time format.

unsigned char year Years. Ranges from 0 to 255, i.e. 1900 (00) to 2155
(255).
unsigned char month Months. Ranges from January (0) to December (11).
unsigned char day Days. Ranges from 1st (0) to 31st (30) day of a month.
unsigned char hour Hours. Ranges from 0 to 23 (24 hours).
unsigned char min Minutes. Ranges from 0 to 59.
unsigned char sec Seconds. Ranges from 0 to 59.
Bool valid Indicates validity of data.

EcAISAntennaPos
Position of the antenna on the ship.

unsigned short a Distance bow - antenna, range: 0 to 511 m.

unsigned short b Distance stern - antenna, range: 0 to 511 m.
unsigned char c Distance port-side - antenna, range: 0 to 63 m.
unsigned char d Distance starbord - antenna, range: 0 to 63 m.
Bool valid Indicates validity of data.

EcAISEta
Estimated time of arrival.

unsigned char month Months. Ranges from January (0) to December (11).
unsigned char day Days. Ranges from 1st (0) to 31st (30) day of a month.
unsigned char hour Hours. Ranges from 0 to 23 (24 hours).
unsigned char min Minutes. Ranges from 0 to 59.
Bool valid Indicates validity of data.

140
 EC2007 ECDIS Kernel Programming Guide

7.11.5 Display of AIS Targets

The display of AIS targets can either be implemented by the application builder utilizing non-
Kernel drawing functions of the GUI toolkit, or by using the Kernel overlay cell approach (see
chapter Overlay Cells). An example implementation of the latter one is given in the Qt based
sample program showAIS.

Please Note:
The requested flashing of AIS target symbols in IEC 62288 is not supported by the EC2007
ECDIS Kernel.

For the display of AIS targets in the overlay cell the object class aistar is used, which has the
following attributes.

Token Name Type Values

mmsino MMSI S MMSI number
actsta Activation status E 1: Sleeping
2: Activated
3: Activated + past position
4: Activated + heading marker
5: Activated + past position + heading marker
6: Selected
7: Selected + past position
8: Selected + heading marker
9: Selected + past position + heading marker
10: Sleeping + vector (COG/SOG)
trksta Tracking status E 1: AIS information available
2: Intruder
3: Dangerous
4: Lost
navsta Navigation status E 1: Under way using engine
2: At anchor
3: Not under command
4: Restricted manoeuverability
5: Constrained by her draught
6: Moored
7: Aground
8: Engaged in fishing
9: Under way sailing
10: Reserved for future amendment of
NavStatus or HSC
10: Reserved for future amendment of
NavStatus or WIG
11: Reserved for future use
12: Reserved for future use
13: Reserved for future use
14: Reserved for future use

141
EC2007 ECDIS Kernel Programming Guide

15: Not defined (default)

16: Emergency
17: Base Station
18: Aid to Navigation
19: Other
tistat Time status E 1: Actual
2: Past
cogcrs Course over ground F 0,0 – 360.0
sogspd Speed over ground F
heading Heading F 0.0 – 360.0
roturn Rate of turn F -99.9 – 99.9
possns Position sensor E 1: Undefined
2: GPS
3: Glonass
4: Combined GPS / GLONASS
5: Loran-C
6: Chayka
7: Integrated Navigation System
8: surveyed
posint Position Integrity E 1: Valid
2: Invalid
imoino IMO Identification S
no
Some of the values are set automatically when the AIS target object is created with
EcAISCreateTargetObject, some have to be set explicitly by the application builder.
The display of AIS targets is regulated in IEC 62288 and depends on the status of the target.

Sleeping A target symbol indicating the presence and orientation of a vessel equipped
with AIS in a certain location. No additional information is presented until
activated thus avoiding information overload.
Activated A symbol representing the automatic or manual activation of a sleeping
target for the display of additional graphically presented information
including: a vector (speed and course over ground); the heading; and ROT or
direction of turn indication (if available) to display actually initiated course
changes.
Selected A symbol representing the manual selection of any AIS target for the display
of detailed information in a separate data display area. In this area, received
target data as well as the calculated CPA and TCPA values will be shown.
Dangerous A symbol representing an AIS target (activated or not) which data contravene
pre-set CPA and/or TCPA limits.
Lost A symbol representing the last valid position of an AIS target before the
reception of its data was lost.

142
 EC2007 ECDIS Kernel Programming Guide

In the EC2007 ECDIS Kernel the status “Selected” and “Activated” are treated as activation
status, “Dangerous” and “Lost” as tracking status.
The function EcAISSetTargetActivationStatus is used to explicitly set the activation status
“Sleeping” and “Activated” of an AIS target object in the overlay cell.
The status “Selected” have to be handled by the application builder, i.e. the application
builder must add the broken square to the original symbol in case the user selected a target.
The tracking status “Dangerous” and “Lost” of a single target of the EcAISTargetInfo
structure can be calculated by the function EcAISCalcTargetTrackingStatus, depending on
safety parameters. The function EcAISSetTargetTrackingStatus is then used to set the tracking
status of the AIS target object in the overlay cell.

Please note:
The cleaning of the AIS overlay cell is in the charge of the application. Usually all lost
targets can be deleted after a certain time with the function EcAISDeleteTargetObject.
After that the overlay cell has to be symbolized with EcChartSymbolizeCell.

7.12 Chart 1
The IHO provides a set of S-57 charts which contain systematically and thematically arranged
chart objects, similar to the INT 1 for paper charts. They are called Chart 1 and part of the
IHO S-52 Standard.
The corresponding SENC charts can be found in $EC2007/data/chart1.
In case an application shall display Chart 1 data, the application has to use the Chart 1
lookup tables. That means that the function EcChartSetLookupTable must not be called with
the parameters EC_LOOKUP_TRADITIONAL or EC_LOOKUP_STANDARD but with the Chart 1
lookup tables which have been loaded before with EcChartAddLookupTable.
const char *lib7csStr = NULL;
int ltChart1;
// Chart 1 lookup tables
char pChart1s[256];
char lChart1s[256];
char aChart1s[256];
char pChart1t[256];
char lChart1t[256];
char aChart1t[256];

if ((lib7csStr = EcKernelGetEnv("LIB_7CS")) == NULL)

{ /* error handling */ }

// load the Chart 1 lookup tables

sprintf(lChart1s, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(pChart1s, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(aChart1s, "%s/lib/preslib4/lookup/[Link]", lib7csStr);

143
EC2007 ECDIS Kernel Programming Guide

sprintf(pChart1t, "%s/lib/preslib4/lookup/[Link]", lib7csStr);

sprintf(lChart1t, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(aChart1t, "%s/lib/preslib4/lookup/[Link]", lib7csStr);

// set the lookup tables for chart 1

if(simplified)
{
ltChart1 = EcChartAddLookupTable(view, pChart1s, lChart1s, aChart1s);
if (!EcChartSetLookupTable(view, ltChart1))
{ /* error handling */ }
}
else
{
ltChart1 = EcChartAddLookupTable(view, pChart1t, lChart1t, aChart1t);
if (!EcChartSetLookupTable(view, ltChart1))
{ /* error handling */ }
}

144
 EC2007 ECDIS Kernel Programming Guide

8 ARCS
The EC2007 ECDIS Kernel supports handling and display of ARCS (Admiralty Raster Chart
Service). ARCS are digital raster charts and published in Hydrographic Chart Raster Format
(HCRF) by UKHO. These raster charts are scanned from traditional paper charts and are
realized as a set of one or more panels. The chart itself is always panel 0 whereas the plans
are panel 1 and further. For details please refer to the document
EC2007_BackgroundInformation.

Please note:
For using the ARCS functionality the ARCS module has to be activated. Please refer to the
Installation Guide.

This chapter describes the essential actions and function calls necessary to install and display
an ARCS chart. The needed functions are explained in detail in the corresponding following
chapters. They also include some more functionality that is not essential for displaying the
chart.
The next two figures give an overview of functions required for the ARCS installation and the
ARCS display.

Figure 13: ARCS Installation Steps

145
EC2007 ECDIS Kernel Programming Guide

Figure 14: ARCS Visualization Steps

8.1 License Conditions

The EC2007 ARCS functionality has been approved by the United Kingdom Hydrographic
Office (UKHO). SevenCs was granted a special ARCS manufacturer’s license that allows the
company to sub-license its approved ARCS module to ECDIS manufacturers. Receiving an
ARCS sub-license from SevenCs means to avoid type approval procedures with UKHO. The
sub-licensee, however, has to adhere to the following conditions.

146
 EC2007 ECDIS Kernel Programming Guide

8.1.1 Manufacture and Promotion

1. It is the responsibility of SevenCs and its sub-licensees to ensure, in respect of the
manufacture and sale of the EC2007 ECDIS Kernel or any product incorporating the
Kernel, that all necessary actions are taken with appropriate export authorities and that
all national regulations are adhered to.
2. SevenCs and its sub-licensees must provide to the UKHO, Admiralty Way, Taunton,
Somerset, TA1 2DN, United Kingdom, copies of all sales and promotion literature related
to the EC2007 ECDIS Kernel or the ARCS-viewer which contains mention to the UKHO
and / or ARCS chart data

8.1.2 Sub Licensing

Following conditions apply on the usage of ARCS Chart Data to be passed on by SevenCs to
sub-licensees:

1. The sub-licencee must provide the UKHO with the name and details of all ARCS
compatible products being produced.
2. The sub-licencee must abide by the following conditions of usage of the ARCS chart
data:
a. If the sub-licencees ARCS-viewer is able to scale the displayed image (such as by
pixel multiplication or sub sampling) then an appropriate warning (e.g. underscale /
overscale) shall be given to the end user. Additionally, to prevent poor quality
images been displayed, any enlargement of an ARCS image shall not be grater than
by a factor of two.
b. If the sub-licencees ARCS-viewer utilizes other digital chart data (other than overlay
information produced by the end user) concurrently with the ARCS chart data, the
sub-licencee must ensure that prominent warnings are displayed on the ARCS-
viewer and that the ARCS-viewer user handbook makes clear the potential
problems associated with this type of operation.
3. The sub-licencee must provide the User Permit and PIN numbers associated with each
system to the end user without constraint.
4. The sub-licencee must ensure that the ARCS-viewer displays any error message related
to the use of the ARCS chart data produced by the EC2007 ECDIS Kernel.

8.1.3 Marking of ECDIS

The form of the marking or wording that can be applied to the ARCS-viewer and / or
included in the sub-licencees sales, promotional and technical literature is to be requested
from the UKHO by writing, if not covered by one or a combination of the following examples:
1. You can use "ARCS" or "Admiralty Raster Chart Service" when describing the ARCS-
viewer and its compatibility with ARCS chart data.

147
EC2007 ECDIS Kernel Programming Guide

2. You can use "The United Kingdom Hydrographic Office" when describing the source of
the ARCS chart data.
3. You can use the United Kingdom Hydrographic Office ARCS logo (in accordance with the
guidance given) solely for the promotion of the ARCS compatibility of the EC2007 ECDIS
Kernel application.

8.2 Registration
In addition to the registration of the EC2007 ECDIS Kernel (see chapter 6.2) two additional
keys (ARCS PIN and ARCS User Permit) are required in order to activate the ARCS module.
These keys are provided by SevenCs along with the registration key whenever an EC2007
Kernel including an ARCS module has been ordered.
The PIN and the user permit also need to be passed to the end user of the finished ARCS
viewer.

8.3 ARCS Directory and File Structure

An ARCS chart CD contains the following directory structure:
ROOT/
RASCHTS/
<GroupID>/ (more than one)
<ChartID> chart files (more than one)

. .
. .
. .
CHARTCAT chart catalogue files
MISC code tables
The RASCHTS directory is divided into a <GroupID> structure because it is inconvenient to
place all files for several hundred charts in one directory. Each <GroupID> directory can
contain up to 100 <ChartID> directories. Finally all files belonging to a single chart are stored
in one <ChartID> directory.
The <GroupID> in which a chart may be found is determined as follows:
• Remove any alphabetic prefixes or suffixes from the <ChartID> to leave the numeric part
only.
• Add leading zeroes to increase the number of characters to five.
• The <GroupID> consists of the three most significant numerals.

148
 EC2007 ECDIS Kernel Programming Guide

The <ChartID> is the chart number as stated on the paper chart, including any prefix and
suffix letters, up to a total of 8 characters.
The following files belong to one chart and are stored in a <GroupID>/<ChartId> directory:
• <ChartID>.HDR Header; general information about the chart
• <ChartID>.CHR Chart raster; tiled raster image in original size (encrypted)
• <ChartID>.CHI Chart index; index file referencing the tiles in the .CHR file
• <ChartID>.LOR Low resolution raster; tiled overview image (encrypted)
• <ChartID>.LOI Low resolution index; index file referencing the tiles in the .LOR file
• <ChartID>.PAL Palette; colour palette to be used when displaying the chart
(encrypted)
The following files exist for each panel of a chart:
• <ChartID>.Pxx* Panel header; panel specific information (encrypted)
• <ChartID>.Nxx Note file; panel specific note references
The "xx" part of the filename extension corresponds to the panel number. The .P00 and .N00
files refer to the main panel and will always be present.
The following are the files for the update tiles located in the same directory as the chart files
but on the update CD:
• <ChartID>.UPR* Update raster; update tiles for the chart image
• <ChartID>.UPI Update index; index file referencing the tiles in the .UPR file
The directory MISC contains six tables listing the meanings of the codes used in the header
files of the charts:
• [Link] Country of origin and producer nation codes
• [Link] Height and depth unit codes
• [Link] Projection codes
• [Link] Horizontal datum codes
• [Link] Height and depth datum codes
• [Link] Note and diagram codes
The ARCS directory structure can be checked with the function EcArcsCheckCD. The function
takes the path to the CD as a parameter and reads the file [Link] in the specified path.
This file contains information about the CD type which is returned by this function. If this file
does not exist the specified path does not hold a valid ARCS directory structure and the
return value is EC_ARCS_CD_UNKNOWN. Otherwise one of the following defines is returned:
EC_ARCS_CD_CHART, EC_ARCS_CD_UPDATE or EC_ARCS_CD_SAMPLE.

149
EC2007 ECDIS Kernel Programming Guide

8.4 ARCS Authorization

Before the EC2007 Kernel can be used to display encrypted ARCS charts the correct PIN must
be set. This PIN is supplied to the application builder by SevenCs together with the ARCS
User Permit. The application builder has to pass these keys on to the end user.
Usually the ARCS PIN has to be defined by the end user once at the very first start of the
application. The function EcArcsCheckPIN is then used to check and set the PIN. It takes a
pointer to the entered PIN as a parameter.
If the check has failed for the third time a delay of 10 seconds is mandatory before the next
check can be made. The delay is incremented by 5 seconds each time another incorrect PIN
is entered. During this delay no check can be made.
The function returns 1 if the PIN is valid, 0 if the PIN is invalid and the next check can be
performed immediately, and n<0 if no PIN check is possible within the next –n seconds. If a
valid PIN has already been set any following calls of the function EcArcsCheckPIN with an
incorrect PIN will not overwrite the valid PIN. In this case the function’s return value is 2.
To find out if the correct PIN has already been entered and to subsequently access
encrypted ARCS charts call the function with the parameter NULL. This will avoid performing
a check.

8.5 ARCS Installation

Before the ARCS charts can be installed a special directory structure has to be created on the
local file system with the function EcArcsCreateSubdirTree. This function creates the same
subdirectory structure as defined for an ARCS chart CD in the given path. The only parameter
is the path in which the directory structure is created. This function does not create the
subdirectories <GroupID>\<ChartID>. This function is usually only called once during the start
of the application.
To install and display ARCS the chart permits must previously be read. After that the ARCS
catalogue on the CD must be read to get the information about the available ARCS. Finally
the individual ARCS charts or updates can be installed.

8.5.1 The ARCS Chart Catalogue

The chart catalogue holds information about all available charts and their inset plans. It is
represented by the following files located in the CHARTCAT directory:
[Link]: holds information about each chart and its main panel as well as references to
the entries for the chart's plans in the file [Link].
[Link]: holds information about all inset plans.
Usually there are two ARCS chart catalogues. One is stored in the local file system and
contains the entire installed ARCS chart database, and the other one is stored on the ARCS
CD from which the charts and updates shall be installed.

150
 EC2007 ECDIS Kernel Programming Guide

The ARCS chart catalogue is represented by an array of EcArcsChartInfo structures which is

created by the function EcArcsInitCharts.

8.5.2 Reading ARCS Chart Permits

Unlike the ARCS charts which are provided on CDs the chart permits are usually provided via
email communication. To read the chart permits into the application they have to be copied
on a medium which can be read by the application.
The permit file is called [Link] if the chart permits are licensed for the Skipper Service and
[Link] if they are licensed for the Navigator Service. In addition to the file containing the
chart permits there is also a file called [Link] holding general information about the owner
of the license on the disc.

Please note:
The chart permit files must be read before the charts are installed.

A chart permit is a combination of encrypted chart key and license information. The chart
key is necessary to decrypt the chart data and the update data. Since the license conditions
differ between the Skipper Service and the Navigator Service this additional information
associated with the chart permit will also differ. Consequently there are a navigator chart
permit (NCP) and a skipper chart permit (SCP), depending on which license type is used.
The function EcArcsReadChartPermits is used to read the chart permits. The parameters are:
• path Path to the location of the [Link] / [Link] and [Link] files
• cp Pointer to the EcArcsChartPermits structure
• errors Pointer to an array of EcArcsPermitError structures
• numOfPermits Number of available chart permits
• allOk Indicates if all chart permit are valid
The structure EcArcsChartPermits is filled with information read from the two files [Link] /
[Link] and [Link] and is needed when checking for a permit of a particular chart or loading
an ARCS chart. When reading the chart permits the function checks if they are valid. For each
chart permit the result of this check is stored in the structure EcArcsPermitError (see
chapter ARCS Error Handling). The function allocates memory for the EcArcsChartPermits and
the EcArcsPermitError structures which explicitly have to be freed with the function
EcArcsReleaseChartPermits and EcFree, respectively.
The format and checksum of the permit files are also checked by the function
EcArcsReadChartPermits before filling the EcArcsChartPermits structure. In case the chart
permits could not be successfully read the function returns the corresponding ARCS error
code (see chapter ARCS Error Handling) and the EcArcsChartPermits structure is NULL.
To store the chart permits on the local file system the function EcArcsCopyChartPermits can
be used.

151
EC2007 ECDIS Kernel Programming Guide

8.5.3 Reading the ARCS Chart Catalogue

The function EcArcsInitCharts retrieves information on all available charts and plans in the
specified path. The parameters are:
• ChartBasePath Path to the chart CD
• UpdateBasePath Path to the update CD
• InfoStruct Pointer to an array of EcArcsChartInfo structures.
The function internally allocates memory for the array of EcArcsChartInfo structures and fills
it. Therefore it is not necessary to call the function EcArcsReleaseCharts to free the allocated
memory after the structures are no longer needed.
In addition to the meta information of the individual chart the path to the update CD is
stored in the EcArcsChartInfo structure since it is needed when updating a chart.
The return value of the function is the number of available charts and plans on success and a
negative number on failure. If the function fails the EcArcsChartInfo structure does not need
to be released.

8.5.4 Installing Charts and Updates

To check if the CD is a regular ARCS CD with charts or if it is an update CD the function
EcArcsCheckCD can be used. Depending on the result, either the charts can be installed or the
updates can be applied.
With the information from the array of EcArcsChartInfo structures it is possible to
implement the selection of the chart or plan which is going be installed. The function
EcArcsGetChartInfoStruct is used to retrieve each element of the array. The parameters are:
• info Pointer to an array of EcArcsChartInfo structures
• idx Index specifying the desired element
The return value is a pointer to the specified EcArcsChartInfo structure. There are several
functions available to read basic information about the charts from the EcArcsChartInfo
structure before the particular chart or plan is installed.

[Link] Installing Charts

In case of a regular ARCS chart CD the function EcArcsInstallChart must be used to install the
chart. This function copies all files of a single chart to the RASCHTS subdirectory of the
specified path. In addition it updates the ARCS chart catalogue file of the specified path. The
parameters are:
• info Pointer to an EcArcsChartInfo structure (one element of the array)
• cp Pointer to an EcArcsChartPermit structure holding all available chart permits
• installPath ARCS root directory where the chart files are to be installed
The function returns True on success or one of the ARCS error numbers (see chapter ARCS
Error Handling) otherwise.
Since only charts with valid chart permits can be installed on the system it is recommended
to call the function EcArcsChartPermitIsAvailable to check for the corresponding permit.
152
 EC2007 ECDIS Kernel Programming Guide

[Link] Installing Updates

ARCS updates are cumulative, therefore only the latest update must be applied. They usually
only consist of the tiles that have been altered.
In case of an ARCS update CD the function EcArcsApplyUpdate must be used. This function
takes the following parameters:
• info Pointer to an EcArcsChartInfo structure (one element of the array)
• cp Pointer to an EcArcsChartPermit structure holding all available chart permits
• error Pointer to an EcArcsPermitError
If a new chart revision is included in the update CD the function will overwrite all old chart
files and then apply the update. The entry in the chart catalogue will be replaced with the
update entry after the chart was successfully updated. To save the location of the updated
tiles on the chart the .UPI file is copied into the subdirectory holding the chart files. This
makes it possible to highlight the updated tiles when the chart is being displayed (see below
for more details).
If an error occurred in the chart permit all information needed to generate the pre-defined
ARCS error message is stored in the EcArcsPermitError structure (see chapter ARCS Error
Handling).
It is also possible to delete a chart using an ARCS Kernel function. The function
EcArcsDeleteChart takes a pointer to the chart information structure as a parameter and
deletes all files of the specified chart. It also removes the corresponding entry in the chart
catalogue file.

[Link] Updating local ARCS Chart Database

After new ARCS charts or updates have been installed the local ARCS chart catalogue is
updated automatically. Before displaying ARCS the array of EcArcsChartInfo structures
representing the local ARCS chart database has to be updated as well with the function
EcArcsInitCharts.

8.6 ARCS Display

Since ARCS charts are scanned paper charts they overlap each other. Therefore it is only
possible to display ONE ARCS chart or plan within a view. The ARCS chart or plan which shall
be displayed can either be selected manually form the list of available charts or semi-
automatically according to the view parameter.

8.6.1 Manual Selection

Appropriate for determining a selection criteria are the two functions EcArcsGetChartTitle and
EcArcsGetChartEdition. A selection based on a specific geographic position can be realized
using the function EcArcsLatLonOnChart
The function EcArcsGetChartTitle reads the chart title, number, scale and centre position of
the chart. The parameters are:

153
EC2007 ECDIS Kernel Programming Guide

• info Pointer to an EcArcsChartInfo structure

• title String to hold the title of the chart
• lenTitle Length of title buffer
• number String to hold the number of the chart
• lenNumber Length of number buffer
• scale Scale of the chart
• lat, lon EcCoordinate variables to hold the latitude and longitude of the chart's centre
position
If only a part of the information returned by this function is desired, for instance title and
number, the rest of the parameters, e.g. scale and centre position, can be NULL.
The function EcArcsGetChartEdition reads the number, title, country of origin, and edition
date of the chart. The parameters are:
• info Pointer to an EcArcsChartInfo structure
• miscDir Path to the MISC directory on the chart CD
• chartNumber String to hold the number of the chart
• chartTitle String to hold the tile of the
• country String to hold the country of origin
• edition String to hold the edition date of the chart
The files listing the meanings of the codes, e.g. country of origin codes, used by ARCS are
located in the MISC directory.
The function EcArcsLatLonOnChart is used to determine if a chart covers the specified
geographic position. The parameters are:
• lat Latitude of position
• lon Longitude of position
• info Pointer to an EcArcsChartInfo structure
The function returns True if the given position is inside the coverage of the specified chart or
plan, False otherwise.
Also helpful when implementing a selection criterion is the function EcArcsIsPlan. It checks if
the specified EcArcsChartInfo structure describes a plan or a chart. The only parameter is a
pointer to an EcArcsChartInfo structure. The function returns True if the given structure is a
plan, and False in case of a chart or sheet of plans.

8.6.2 Semi-Automatic Selection

The semi-automatic selection works similar to the automatic selection of the SENC charts
(see chapter Chart Loading) based on the SENC catalogue. Similar to the SENC catalogue a
catalogue has to be created with the function EcArcsCreateCatalogue. The location of this
catalogue is defined within the array of EcArcsChartInfo structures which is passed to the
function.

154
 EC2007 ECDIS Kernel Programming Guide

Please note:
The catalogue has to be updated whenever new ARCS charts or updates have been
installed.

The function EcArcsFindChart searches for ARCS charts depending on the passed coordinates.
It returns the number of found charts and an array of EcCatEntry structures. The next step is
up to the application builder to choose the proper ARCS chart for the given view, e.g. by
comparison of the display scale with the scales of the charts, retrieved from the EcCatEntry
structure.
The application must release the memory by calling EcFreeCatEntries if the returned number
of entries in the array is greater 0.

8.6.3 Checking for the Chart Permit

Once a specific chart or plan has been selected it is necessary to check if an appropriate and
valid chart permit is available before the chart or plan can be visualized.
The function EcArcsChartPermitIsAvailable checks if a chart permit is available for the
specified chart and if it is valid. The parameters are:
• info Pointer to an EcArcsChartInfo structure (one element of the array)
• cp Pointer to an EcArcsChartPermits structure (containing all chart permits)
• error Pointer to an EcArcsPermitError structure
This function scans the chart permits structure for the permit corresponding to the specified
chart. If the permit was found the structure EcArcsPermitError is filled and can be checked
for possible errors. In case of an error this structure holds all information needed to
generate the pre-defined error or warning messages. The function EcArcsGetErrorMessage
can be used to retrieve this error message (see chapter ARCS Error Handling).

8.6.4 Loading an ARCS Chart

Before loading a chart or plan a view must be created. This is independent of ARCS charts
and therefore the Kernel functions EcChartViewCreate and EcDraw[NT|X11]Initialize (see
chapter Chart Display) are used to create a view structure.

Please note:
There is no need to have separate view structures for the display of S-57 or ARCS charts.
You can handle either only S-57 or only ARCS or S-57 combined with ARCS in one view. In
that case the functions EcChartUnloadView and EcArcsUnloadChart have to be used each
time before switching to the other chart display.

When displaying an S-57 cell it is possible to specify the range and alignment of the image
within the view. This cannot be done with ARCS charts. Reducing the size of a raster chart
image would result in information and quality loss, so it is not allowed to scale an ARCS
chart. To compensate this drawback there are two images for each chart. The first holds the

155
EC2007 ECDIS Kernel Programming Guide

chart image in original size and the second contains an overview image of the same chart
reduced by a factor of six.
When loading a chart one of these image types can be selected. Also because of possible loss
of quality it is only allowed to rotate an ARCS chart by 90°, 180° or 270°. However, if a paper
chart is rotated the angle may be random and not necessarily one of these values (e.g. chart
2642 – "Sound Of Harris" is rotated by an angle of 45°). As a result it is not possible to display
all charts "north up" which is why SevenCs decided to display the charts in the same
alignment as the original paper chart and does not support any rotation.
With the information from the array of EcArcsChartInfo structures it is possible to
implement the selection of the chart or plan which is going be displayed. The function
EcArcsGetChartInfoStruct (see chapter Installing Charts and Updates) is used to retrieve each
element of the array.
The function EcArcsLoadChart loads the specified chart from the ARCS database and assigns it
to the given view. The parameters are:
• view Pointer to the current view structure
• info Pointer to an EcArcsChartInfo structure (one element of the array)
• chart_type Image type
• cp Pointer to an EcArcsChartPermit structure holding all available chart
permits
• colorScheme ARCS colour scheme specifying the light conditions
The third parameter specifies the image type which can be either
EC_ARCS_CHART_TYPE_OVERVIEW
or
EC_ARCS_CHART_TYPE_CHART.
The last parameter specifies the ARCS color scheme which can be one of the following
values: EC_ARCS_DAY
EC_ARCS_DUSK
EC_ARCS_NIGHT.
When using this function it is important to evaluate the return value. This function returns
ARCS_NOERR on success, otherwise an ARCS error code (see chapter ARCS Error Handling).

8.6.5 Setting ARCS Colors

Between loading and drawing the chart the ARCS colors should be set to ensure the correct
display of the ARCS chart. Two versions of the function EcArcs[NT|X11]SetColorScheme are
available, one for the supported Windows operating systems and one for the UNIX X11
environment. The functions both read and decrypt the ARCS color data and set these colors
for the given view.
EcArcsNTSetColorScheme takes the following parameters:
• view Pointer to the current view structure

156
 EC2007 ECDIS Kernel Programming Guide

• info Pointer to an EcArcsChartInfo structure (one element of the array)

• cp Pointer to an EcArcsChartPermit structure holding all available chart permits
• dc Device context to be used, may be NULL
• colorScheme ARCS color scheme specifying the light conditions
• grayflag Value True turns colors into shades of gray
• brightness Overall brightness of colors in percent (0…100)
• offset Start offset for used palette indices; (0…offset) will not be used for ARCS
colors
This function returns the new palette object on success and NULL on failure. When it is no
longer needed this palette has to be deleted by the application using the Windows function
DeleteObject.

[Link] ARCS Plus Overlay

If an overlay is to be drawn on top of the chart image, e.g. for displaying a ship symbol or
radar image, it is not recommended to use the function EcArcs[NT|X11]SetColorScheme to
handle the ARCS colors. The function library provides an alternative and more flexible way to
set the ARCS colors in the system palette:
This is realized with the function EcArcsGetColorTable. This function retrieves the red-green-
blue definitions of the colors used in the specified chart. The system's color palette must
then be set and realized with the appropriate Windows functions.
The function takes the following parameters:
• info Pointer to an EcArcsChartInfo structure (one element of the array)
• cp Pointer to an EcArcsChartPermit structure holding all available chart
permits
• colorScheme ARCS color scheme specifying the light conditions
• rgbs Array of the structure EcColorEntry holding the red-green-blue
definitions of the colors
The EcColorEntry structure has the following members:
• idx Color index used in the raster image
• red Red definition of the color
• green Green definition of the color
• blue Blue definition of the color
The memory for the array of EcColorEntry structures is allocated by the function and should
be freed by EcFree.
The function EcArcsSetColorIndex is used to set the color index mapping for converting ARCS
colors into drawing colors. The parameters are:
• view Pointer to the current view structure
• table Array of logical color indices
• tsize Size of table

157
EC2007 ECDIS Kernel Programming Guide

The function EcArcsGetColorIndex is used to retrieve the logical color index of an ARCS color.
The parameters are:
• view Pointer to the current view structure
• col ARCS color index
This function returns the logical color index that can be used as an index into the logical
system palette.
The following example shows the color handling using the function EcArcsGetColorTable and a
start offset for the color indices.

8.6.6 Drawing the Chart or Plan

After the ARCS colors have been set the chart assigned to the current view can be drawn
with the function EcArcs[NT|X11]DrawChart.
The function EcArcs[NT|X11]DrawChart draws the currently loaded chart into a window of
given size. The parameters are:
• view Pointer to the current view structure
• dc Device context to be used
• dx0, dy0 x-y-coordinates of upper left corner of the clipping window
• dx1, dy1 x-y-coordinates of lower right corner of the clipping window
• lat, lon Latitude and longitude of the center position on the
• chart Display of type EcCoordinate
• patchFlag Indicates that inset plans shall be blanked
The last parameter indicates whether the inset plans of the chart are blanked out or shown.
The parameter is of type EcArcsPlanHandling and the value can be EC_ARCS_PATCH_PLANS
or EC_ARCS_SHOW_PLANS. It is recommended to blank out the plan by setting the
parameter to EC_ARCS_PATCH_PLANS when displaying the chart. This will avoid the
problem of having the same geographic position more than once in the display. If needed,
the plans can be loaded and drawn separately from the chart.
The centre position on the chart can be randomly set. In case the specified position is not
located inside the bounding box of the chart or plan the closest point on the border of the
bounding box is used as the centre position instead.
The centre of the chart is returned by the function EcArcsGetChartTitle described above. This
may, however, be an inaccurate value. Once the chart is loaded the function
EcArcsGetChartCenter can be used to retrieve the exact centre of the chart.

Please note:
The quality of the ARCS display on Linux systems is NOT as good as it is on Windows
systems.

158
 EC2007 ECDIS Kernel Programming Guide

8.6.7 Indicating and Viewing ARCS Updates

To highlite the chart tiles of the chart or plan that have been changed in the update last
applied the function EcArcs[NT|X11]ShowUpdateLocation can be used. The parameters are:
• view Pointer to the current view structure
• dc Device context to be used for the drawing commands
The following example shows the use of this function. The color used to highlight the
updated tiles in this example has the ARCS color index 2 (magenta solid). The current pen,
brush and background mode can also be saved and then restored after visualizing the
update tiles.
int colIdx;
LOGBRUSH myBrush;
HBRUSH hBrush;
HPEN hPen;
HDC dc;

colIdx = EcArcsGetColorIndex(view,2);

[Link] = PALETTEINDEX(colIdx));
[Link] = BS_HATCHED;
[Link] = HS_FDIAGONAL;
hBrush = CreateBrushIndirect(&myBrush);

hPen = CreatePen(PS_SOLID, 1, PALETTEINDEX(colIdx));

DeleteObject(SelectObject(dc,hPen));
DeleteObject(SelectObject(dc,hBrush));
SetBkMode(dc,TRANSPARENT);

EcArcsNTShowUpdateLocation(view, dc);

When the ARCS chart is displayed in a window it is also possible to draw user-defined objects
on top of the chart image. This is useful when realizing route planning or drawing user-
defined notes on the chart. To avoid drawing outside the chart image the function
EcArcs[NT|X11]CreateChartClipMask can be called. This function creates a clip mask covering
the entire chart or plan being displayed. When drawing user-defined objects those located
outside this clip mask will not be displayed.
The function EcArcs[NT|X11]CreateChartClipMask only takes a pointer to the current view
structure as a parameter. Releasing the clip mask is the responsibility of the ARCS-viewer
application.

Please note:
A clip mask for the displayed chart should not be set when the update tiles are
highlighted. It might be that the border of the chart image has been updated. In that case
it would not be highlighted.

159
EC2007 ECDIS Kernel Programming Guide

When an inset plan is displayed and the updates are highlighted the clip mask should be set
with the function EcArcsNTCreateChartClipMask.
The following example shows how the function EcArcsNTCreateChartClipMask is used in
combination with EcArcsNTShowUpdateLocation. The function SelectClipRgn is a Windows
function which selects a region as the current clipping region for the specified device
context.
EcArcsChartInfo *currentInfo;
HRGN tempClipMask; //temporary clipmask for ARCS presentation
int ret;
HDC dc;

if (EcArcsIsPlan(currentInfo))
{
// set the plan bounding box as clip mask
tempClipMask = EcArcsNTCreateChartClipMask(view);
ret = SelectClipRgn(dc, tempClipMask);
}

// call EcArcsNTShowUpdateLocation as described in previous example

if (EcArcsIsPlan(currentInfo))
{
// remove the clip mask
SelectClipRgn(dc, NULL);
DeleteObject(tempClipMask);
}

8.7 Releasing Resources

When a particular chart is no longer accessed it should be unloaded and unassigned from
the current view. This task is realized with the function EcArcsUnloadChart. This function only
takes a pointer to the current view as parameter. It unloads the currently loaded chart from
the view and frees resources that are no longer needed. The view structure will not be freed,
so that a new chart can be loaded and assigned to this view after calling EcArcsUnloadChart.
If no more ARCS charts are to be displayed the memory of the EcArcsChartInfo structure
allocated by EcArcsInitCharts has to be freed. The function EcArcsReleaseCharts takes a pointer
to an array of this structure as a parameter and frees the memory allocated for it.
In case no more ARCS charts are to be displayed the chart permits kept in the
EcArcsChartPermits structure are also no longer needed. The function
EcArcsReleaseChartPermits is used to free the memory of this structure allocated by the
function EcArcsReadChartPermits. A pointer to a structure containing the chart permits is
passed to the function which returns ARCS_NOERR on success and
ARCS_UNKNOWN_LICENCETYPE if an unknown license type was detected and the memory
could not be released. Since there are two different types of chart permits the
EcArcsReleaseChartPermits function checks the structure type. The error
ARCS_UNKNOWN_LICENCETYPE does not occur unless the internal structure has been
damaged.

160
 EC2007 ECDIS Kernel Programming Guide

Additionally the array of EcArcsPermitError needs to be freed by the application. The

function EcFree can be used for this purpose.
The view structure is not freed by any of these functions. If it is no longer used, e.g. to
display S-57 chart data, it has to be freed with the EC2007 Kernel function EcChartViewDelete
which is described in the Programming Guide.

8.8 Additional Chart Permit Handling

Besides the mere reading of the ARCS chart permits (see chapter Reading ARCS Chart Permits)
the EC2007 ECDIS Kernel provides functions to handle ARCS chart permits.
The function EcArcsGetPINEntryText loads specific information from the file [Link] and
returns a pre-defined message text which has to be shown together when entering the PIN.
The parameters are:
• path Path to the location of the [Link] file
• lcnData Array of six strings containing the first six entries of the [Link] file
• message Pointer to a string containing the given ARCS message
This function allocates memory for the strings of lcnData and message which have to be
freed by the application using EcFree
The function EcArcsCopyChartPermits is used to copy the chart permit files into a specific
directory. The parameters are:
• permitPath Destination path
• copyFromPath Path to the location of the [Link] / [Link] and [Link] files
• errors Pointer to an array of EcArcsPermitError structures
• numOfPermits Amount of available chart permits
• allOk Indicates if all chart permit are valid
This function copies both the [Link] file containing general information on the license
owner and either the [Link] or [Link] file depending on the license type (skipper or
navigator service). The permit files in the destination path will be overwritten. The array of
EcArcsPermitError structures returns the result of the chart permit check for each available
permit in the specified files (see chapter ARCS Error Handling).
The next function is used to add a new chart permit to the already existing file of chart
permits. When a user receives the chart permit in verbal or printed form it must be possible
to manually enter these chart permits into the ARCS viewer. This string can then be added to
the [Link] or [Link] file with the function EcArcsAddSingleChartPermit. This function extracts
the license type from the [Link] file in the specified path and checks if it matches the type
of the given chart permit. The chart permit is then appended to the corresponding file
([Link] or [Link]). The parameters are:
• permitPath Path to the location of the [Link] / [Link] and [Link] files
• permit String holding the new permit which is to be added.
• overwrite Flag to control the behavior in case an existing permit is found

161
EC2007 ECDIS Kernel Programming Guide

This function also checks the structure and checksum of a chart permit that was manually
entered into the system. If the files [Link] / [Link] and [Link] do not exist no chart permits
have been delivered yet.
The file [Link] can be created with the function EcArcsCreateLCNFile. The parameters are:
• pType License type stored in the [Link] file
• path Ppath where the [Link] file shall be stored
The created [Link] file will contain all the necessary general information on the license
owner and license type needed to handle chart permits with the ARCS functions. If the file
[Link] already exists in the given directory the function will return the error
ARCS_INVALID_FILE and the existing file is not overwritten.
The function EcArcsAddSingleChartPermit will create a [Link] or [Link] file if they do not
exist, depending on the license type stored in the [Link] file.
To explicitly retrieve the information about the license type from the [Link] file the
function EcArcsGetPermitType is used. The parameters are:
• path Path where the [Link] file is located
• pType License type retrieved from the [Link] file
When purchasing additional chart permits they might be supplied in printed form as
mentioned above or in a supplementary file. If the previously supplied chart permit file still
contains valid permits an ARCS viewer has to be able to merge the two files, provided they
are of the same type. It must be ensured that none of the already existing chart permits are
overwritten or deleted.
The function EcArcsMergeChartPermitFiles is used to merge two permit files of the same type.
The parameters are:
• permitPath Path to the location of the [Link] / [Link] and [Link] files
• newPath Path to the location of the new permit file which is to be added
• overwrite Flag to control the behavior in case an existing permit is found
• errors Pointer to an array of EcArcsPermitError structures
• numOfPermits Amount of new chart permits
• allOk Indicates if all chart permit are valid
This function extracts the license type from the [Link] file in the specified path and checks
if it matches the type of the new chart permit file. The array of EcArcsPermitError structures
returns the result of the chart permit check for each new permit added to the already
existing chart permit file. The memory for this array is allocated by the function and needs to
be freed by the application using EcFree.
It is also useful to be able to remove expired, invalid or damaged chart permits from the
chart permit file. The function EcArcsRemoveChartPermit removes the chart permit for the
specified chart from the given chart permit file. The parameters are:
• chartNumber String containing the chart number specifying the chart permit to be
deleted.
• path Path to the location of the chart permit file

162
 EC2007 ECDIS Kernel Programming Guide

There are three functions that extract special values from a chart permit of a specific chart.
All functions take a chart information structure, the structure containing the chart permits,
and a pointer to an integer variable as parameters. The desired values from the chart permit
are stored in the integer variable.
The function
• EcArcsGetPenc retrieves the encryption version number of the chart permit,
• EcArcsGetPNM gets the notices to mariners number, and
• EcArcsGetPseq gets the sequential issue number of the permit.
These values are needed for some ARCS error messages that are precisely defined by the
UKHO (see chapter ARCS Error Handling). The return value of these functions is True on
success and False otherwise.
It is very important to consider the license type when handling the chart permit files. If chart
permits of both license types exist the files must be kept in different directories. This is
essential because in both cases the general information about the license owner and the
license type is stored in the file named [Link].

8.9 ARCS Demonstration Mode

The EC2007 ECDIS Kernel provides a method for testing the ARCS functions without having
valid chart permits: the ARCS demonstration mode. The function EcArcsSetDemoMode is used
to switch between normal ARCS mode and this special demonstration mode. In this mode,
ARCS sample data (charts and permits) provided by UKHO can be used even on unregistered
systems. The chart permits for the sample data have to be installed and the fixed PIN for
data access is '1234'. In demo mode, normal ARCS data cannot be accessed. A mode change
invalidates currently allocated data structures. Thus, the mode change has to be done before
EcArcsInitCharts is called.

Please note:
In demonstration mode standard ARCS charts (even with valid chart permits) cannot be
used. Sample data and permits for the demonstration mode are included in the ECDIS
Kernel delivery.

The function EcArcsGetDemoMode retrieves the currently set ARCS mode which can be one of
the following values: ARCS_MODE_DEMO or ARCS_MODE_NORMAL.

8.10 Additional ARCS Functions

There are some additional helpful but not mandatory functions for the use of ARCS. For the
respective list of parameters please refer to the Function Reference.

163
EC2007 ECDIS Kernel Programming Guide

8.10.1 Chart Information

The following functions extract important data from a chart which has not been loaded yet.
The chart is specified by passing the chart information structure.
• EcArcsChartIsEncrypted checks if an ARCS chart is encrypted (most ARCS charts are
encrypted and therefore a special chart permit is needed to be able to display the chart.
There are nevertheless some charts which are not encrypted and can be displayed without
any permits).
For the ARCS display the following functions might be usefull:
• EcArcsGetChartCenter gets the exact centre position of the currently loaded chart. This
value is in local datum.
• EcArcsGetChartScale gets the scale of the currently loaded chart. The return value is the
reciprocal value of chart's scale, e.g. 40000 if the scale is 1:40000.
• EcArcsGetRange gets the range (half the height) of the given rectangular display window
based on the currently loaded ARCS chart. The return value is the range in nautical miles.
• EcArcsGetImageSize gets the width and height of the currently loaded chart or plan image.
To receive general information of an ARCS chart following functions might be usefull:
• EcArcsIsPlan checks if the specified chart catalogue entry describes a plan or a chart. This
function returns a boolean value.
• EcArcsGetChartCorrectionState retrieves the date of the latest notices to mariners, the
publication date of the last applied update, and the explanatory text from the chart
catalogue. The values are stored in the two additional parameters of the function.
• EcArcsGetChartDatum retrieves the horizontal, depth, and height datum as well as the
depth and height units of the specified chart. The function additionally needs the path to
the MISC directory containing the tables to convert the code into human readable text.
• EcArcsGetChartEdition retrieves the chart number and title as well as the country of origin
and the edition date. This function also takes the path to the MISC directory as an
additional.
• EcArcsGetChartTitle retrieves the title, number, scale, and centre position of the specified
chart.
• EcArcsGetChartProjection retrieves the chart projection. This function also takes the path to
the MISC directory as an additional parameter.
• EcArcsGetChartCoverage retrieves the number of vertices specifying the chart or plan
coverage together with an array of the latitudes and longitudes of their positions.
• EcArcsGetRCID retrieves the raster chart issue date of the specified chart. This value is
needed for some ARCS defined error messages described in chapter ARCS Error Handling.
• EcArcsGetENC retrieves the encryption version of the specified chart. This value is needed
for some ARCS defined error messages described in chapter ARCS Error Handling.
• EcArcsGetUNM retrieves the latest notices to mariners date of update for the specified
chart from the chart catalogue of the update CD. This value is needed for some ARCS
defined error messages described in chapter ARCS Error Handling.

164
 EC2007 ECDIS Kernel Programming Guide

The functions take strings as parameters to return the retrieved data allocate the memory
for these variables internally. The memory should be freed by the application using the
function EcFree.

8.10.2 Chart Notes

Often there is additional information shown on the chart as notes. Because these notes are
not displayed inside the corresponding panel their connection is stored in reference lists as
part of the chart data. An ARCS-viewer has to be able to show both the chart or plan and the
notes at the same time, because the information can be important for the safety of a vessel.
The following functions are available to handle these notes on the chart:
• EcArcsGetNumberOfNotes retrieves the number of notes on the currently loaded ARCS
chart.
• EcArcsNoteFullname returns a note's name as plain text. The return value is a pointer to the
corresponding static buffer and may not be freed.
• EcArcsNoteGetDimension gets the width and height of the chart area in which the specified
note is located. This function returns True on success and False on failure.
• EcArcsNoteGetCenter gets the geographic coordinates of the center position of the chart
rectangle holding the note. This function returns True on success and False on failure.
• EcArcs[NT|X11]DrawNote draws the chart area containing the specified note into the given
pixmap. The drawing area of the pixmap can be specified and it is recommended to use at
least the dimensions of the note area to ensure that the entire note is displayed.

8.10.3 Coordinate Conversion Functions

Each sub-panel of an ARCS chart contains two sets of parameters that are used to transform
world coordinates into device coordinates and vice versa. The world coordinates are always
expected in local datum which can differ from sub-panel to sub-panel. Due to this a plan may
have a different local datum than the chart. It is also possible to have different local datums
inside a panel that is split into sub-panels.
The transformation from device coordinates into world coordinates in local datum and vice
versa can be realized with the two EC2007 Kernel functions EcDrawLatLonToXy and
EcDrawXyToLatLon. Since there are no transformation parameters defined for positions
outside any sub-panel the EC2007 Kernel uses the sets of the closest sub-panel. However,
these results may be incorrect. The resulting problems can be avoided by setting a clip mask
to avoid drawing outside the chart coverage, or by replacing the position with the closest
point on the border of the chart.
To ensure always having valid coordinates there are two conversion functions that return
the closest point on the border of the currently loaded chart or plan in case the input
coordinates are outside the chart's or plan's coverage.

165
EC2007 ECDIS Kernel Programming Guide

EcArcsLatLonToImageOnChart converts world coordinates into device coordinates. If the input

coordinates are outside the loaded chart or plan the closest point on the border of the chart
or plan is returned.
EcArcsImageToLatLonOnChart converts device coordinates to world coordinates. If the input
coordinates are outside the loaded chart or plan the closest point on the border of the chart
or plan is returned.
In case the geographic position is in WGS84 datum, e.g. vessel position supplied by GPS or
object position from the SENC database, or the position retrieved from the chart should be
in WGS84 format the two functions EcArcsWGS84ToImageOnChart and
EcArcsImageToWGS84OnChart can be used.
These functions are analogue to the two functions mentioned above. If the WGS84
polynoms for coordinate transformation are not known the function uses the polynom for
local datum and additionally returns ARCS_WGS84_UNKNOWN.

8.11 ARCS Error Handling

For ARCS error handling several defines have been set which are used as return values for
most of the ARCS functions to determine if an error has occurred.
The return value ARCS_NOERR implies that no error has been detected and the current
process can continue.

8.11.1 Security Errors

The extensive security scheme devised by the UKHO for the use of their ARCS charts also
specifies a display of defined error messages and error handling. Errors related to the ARCS
security scheme may arise in the following functions:
• EcArcsReadChartPermits
• EcArcsChartPermitIsAvailable
• EcArcsCopyChartPermits
• EcArcsMergeChartPermitFiles
• EcArcsApplyUpdate
The functions:
• EcArcsReadChartPermits,
• EcArcsCopyChartPermits, and
• EcArcsMergeChartPermitFiles
allocate memory for the EcArcsPermitError structure. All functions listed above fill the
structure with all necessary information to display the ARCS pre-defined error messages in
case of an error. This structure defines the following fields:
• ErrStatus Integer variable holding the ARCS error code

166
 EC2007 ECDIS Kernel Programming Guide

• ChartNumber String holding the corresponding chart number

• RCIssueDate String holding the raster chart issue date
• NM Long variable holding the latest notices to mariners number
• PNM Long variable holding the permit notices to mariners number
• UNM Long variable holding the update notices to mariners number
• Enc Integer variable holding the encryption version
• Penc Integer variable holding the permit encryption version
• Seq Integer variable holding the sequential issue number
• Pseq Integer variable holding the permit sequential issue number
The ARCS pre-defined error messages can be retrieved with the function
EcArcsGetErrorMessage. It takes an EcArcsPermitError as only parameter and returns a string
holding the ARCS error message with all the necessary values stored in the error structure
placed inside the message text.
The following error defines are set. For each there is a certain message which the application
shall display in case of failure:

ARCS_ERR01: A checksum error is detected while reading the [Link] file. It is allowed
to continue but the following message should be displayed:
ARCS01: The contents of the [Link] file have been altered. You may be
in breach of the licensing arrangements that relate to the use of the
charts. License is invalid. Please contact your ARCS agent / distributor to
correct this error.
ARCS_ERR02: An invalid checksum is detected in a chart permit. The ARCS-viewer has
to stop the current task and display the following message:
ARCS02: Chart chart#. Chart Permit corrupted. Please reload from the
original media.
ARCS_ERR03: The update relates to newer version of the chart. Stop and show the
following message:
ARCS03: Chart chart#. Update information relates to a newer version of
the chart. Please load the chart CD that contains chart# with an issue
date of rcid (raster chart issue date).
ARCS_ERR04: The chart is of newer version than the update. Stop and show the
following message:
ARCS04: Chart chart#. The chart data already incorporates this update
information. Please load the latest update CD.
ARCS_ERR05: The license has expired and the navigator service is being used. Stop with
following message:
ARCS05: Chart chart#. License expired – updating is not permitted.
Please contact your agent to re-new license.
ARCS_ERR06: The license is valid for a newer update and the skipper service is being
used. Continue the current task but show the following warning
message:
ARCS06: Chart chart#. Corrections have been loaded to NtoM unm#.
167
EC2007 ECDIS Kernel Programming Guide

License is valid to NtoM pnm#. Corrections are missing. Please insert the
update CD that contains corrections for NtoM pnm#.
ARCS_ERR07: The license is only valid for an older update and the skipper service is
being used. Stop the task and show the following message:
ARCS07: Chart chart#. License not valid for this update. Please contact
your ARCS distributor if you wish to use this data.
ARCS_ERR08: The NCP for the desired chart will expire in less than one month. The
chart and any update data has to be shown with the warning:
ARCS08: Warning – License expires in less than one month. Please
contact your ARCS agent for a license renewal.
ARCS_ERR09: The NCP for the desired chart has expired not longer than one month
ago. The chart and any update data has to be shown with the following
permanent warning:
ARCS09: Chart chart#. Warning – License expired. The displayed chart
may not be up to date. Contact your ARCS agent to arrange for a license
renewal.
ARCS_ERR10: The NCP for the desired chart has expired more than one month ago. The
current task has to stop with the following message:
ARCS10: Chart chart#. License expired. ARCS charts cannot be displayed.
Contact your ARCS agent for a license renewal.
ARCS_ERR11: The chart encryption version number (enc) is smaller than the permit
encryption version number (penc) and a navigator service is used. The
current task has to stop with the following error message:
ARCS11: Chart chart#. The loaded version of this chart is too old to be
used with the license. Please load a more recent version of the chart.
Chart version is enc#, Permit version is penc#.
ARCS_ERR12: The enc is by at least one greater than the penc (this condition should
never be reached since the licence will have expired before). Stop with
the following error message:
ARCS12: Chart chart#. The license is too old to be used with this version
of this chart. Please contact your ARCS agent to obtain a new license.
ARCS_ERR13: The permit's sequential issue number (pseq) is smaller than the chart's
(seq) and a skipper service is used. Stop the current task and display the
following error:
ARCS13: Chart chart#. The license is not valid for this version of the
chart. Either load the version with an issue number of pseq# or contact
your ARCS distributor to update your license.
ARCS_ERR14: The pseq is greater than the seq. Decryption is also denied and the
following error has to be displayed:
ARCS14: Chart chart#. The loaded version of the chart is older than the
one for which the license is valid. Please load the more recent version
with an issue number of pseq#.
ARCS_ERR15: The permit's notices to mariners number (PNM) is smaller than the
actual notices to mariners numbers of the chart (NM) and update (UNM)
and a skipper service is used. The chart is not decrypted and the

168
 EC2007 ECDIS Kernel Programming Guide

following error message has to be displayed:

ARCS15: Chart chart#. The license is not valid for this version of the
chart. Please contact your ARCS distributor to update your license.
ARCS_ERR16: The PNM is less then the UNM and a skipper service is used. The chart is
shown but the following warning has to be displayed permanently:
ARCS16: Chart chart#. Warning - License does not allow access to latest
correctional information. License is valid to NtoM correction pnm#.
Updates are available for NtoM correction unm#. Please contact your
ARCS distributor to update your license.
ARCS_ERR17: The PNM is greater than the UNM. The chart is displayed including any
update information together with the following permanent message:
ARCS17: Chart chart#. Warning - License is valid to NtoM correction
pnm#. Corrections are loaded to NtoM correction unm#. Corrections are
missing. Please load update CD that contains NtoM correction pnm#.
ARCS_ERR18: The PNM is greater than the NM but there is no update data. The chart is
displayed together with the following permanent warning:
ARCS18: Chart chart#. Warning - License is valid to NtoM correction
pnm#. The chart is corrected to NtoM correction nm#. Corrections are
missing. Please load update CD that contains NtoM correction pnm#

In these predefined messages the italic text needs to be replaced by its current value. This
can be accomplished by passing the returned error structure to the function
EcArcsGetErrorMessage as described above, or by retrieving these values with special ARCS
functions. The following list shows the values needed in some messages together with the
functions with which they can be obtained.

chart# The chart number can be retrieved with the function EcArcsGetChartEdition
rcid The raster chart issue date can be retrieved with the function EcArcsGetRCID
nm# The number of latest notices to mariners can be retrieved with the function
EcArcsGetChartCorrectionState
unm# The number of latest notices to mariners for the chart update can be retrieved
with the function EcArcsGetUNM
enc# The encryption version for the chart can be retrieved with the function
EcArcsGetENC
pnm# The permit's number of latest notices to mariners for the chart update can be
retrieved with function EcArcsGetPNM
penc# permit's encryption version can be retrieved with the function EcArcsGetPenc
pseq# The permit's sequential issue number can be retrieved with the function
EcArcsGetPseq

Aside from the 18 defined error codes some combinations are also possible as return values.
Then it is necessary to display both error messages.

169
EC2007 ECDIS Kernel Programming Guide

ARCS_ERR08_AND_11: both the ARCS08 and ARCS11 errors have been detected.
ARCS_ERR08_AND_12: both the ARCS08 and ARCS12 errors have been detected.
ARCS_ERR09_AND_11: both the ARCS09 and ARCS11 errors have been detected.
ARCS_ERR09_AND_12: both the ARCS09 and ARCS12 errors have been detected.
ARCS_NO_PIN: PIN has not been set

8.11.2 Internal Kernel Error Messages

While internally accessing data or files the following ARCS Kernel errors may occur:

ARCS_INVALID_LCN: the specified format does not match the

ARCS_INVALID_SCP: [Link] or [Link] or [Link] file structure
respectively.
ARCS_INVALID_NCP:
ARCS_INVALID_CHART_CAT; the specified format does not match the
ARCS_INVALID_PLAN_CAT: [Link] or [Link] file structure
respectively
ARCS_INVALID_PTR: the specified format does not match the
ARCS_INVALID_HDR: <ChartID>.PTR or
<ChartID>.HDR or
ARCS_INVALID_IDX:
<ChartID>.IDX or
ARCS_INVALID_PAL: <ChartID>.PAL or
ARCS_INVALID_PXX: <ChartID>.PXX
file structure respectively.
ARCS_INVALID_FILE: the specified file cannot be opened or
read/write access attained
ARCS_INVALID_CP: at least one invalid chart permit was found.
ARCS_UNKNOWN_CHARTTYPE: an unknown chart or licence type is detected
ARCS_UNKNOWN_LICENCETYPE: respectively
ARCS_NO_PERMIT_FOUND: no permit was found for the specified chart
ARCS_PERMIT_FOUND: permit already exists for the specified chart.
ARCS_NEWER_PERMIT_AVAILABLE: newer permit was found for the specified
chart
ARCS_PERMIT_RELOADED: newer permit was replaced by an older one
ARCS_NO_CHARTPERMIT: the specified structure is not a chart permit,
ARCS_NO_CHARTHEADER: chart header or chart information structure
respectively.
ARCS_NO_CHARTINFO:
ARCS_CRCCHECK_FAILED: the crc-check for the .CHR or .CHI file has
failed
ARCS_OUTSIDE: the specified position is outside the chart
bounding box

170
 EC2007 ECDIS Kernel Programming Guide

ARCS_WGS84_UNKNOWN: the WGS84 coefficients for conversion are

unknown
ARCS_OUTSIDE_AND_WGS84_UNKNOWN: combination of ARCS_OUTSIDE and
ARCS_WGS84_UNKNOWN
ARCS_NO_CHART_CD: the expected ARCS chart CD or ARCS update
ARCS_NO_UPDATE_CD: CD could not be detected respectively
ARCS_NO_CHARTS no ARCS charts or ARCS permits could be
ARCS_NO_PERMITS: found in specified directory respectively
ARCS_CANNOT_ALLOC_MEM: the function cannot allocate the needed
memory
ARCS_DIFFERENT_PERMITTYPE: the specified permit types do not match
(when merging permits).

171
EC2007 ECDIS Kernel Programming Guide

9 Non-ENC Products
The standard chart display application, e.g. an ECDIS or VTS, usually deals with official ENCs
only. However, there are many other applications, e.g. InlandECDIS, WECDIS or Combat
Management Systems, which have to deal with other chart products as well. The following
chapters describe how to deal with such non-ENC chart products. For a general description
of these chart products please refer to the document EC2007_BackgroundInformation.
The simultaneous handling of different products in the same application is not regulated in
any standard. Therefore the application builder must define the handling. The EC2007 ECDIS
Kernel offers various possibilities to configure the behavior of the application when it comes
to handling different chart products.
In general all S-57 based (ENC, IENC, AML) and VPF based chart products (DNC, VMap, TOD)
should be stored in different DENC structures and displayed in different views. Different
chart products in the same view can be separated with the function EcChartSetCellLoadFilter.
This function specifies filter criteria for the cell loading functions EcDraw[NT|X11]DrawChart,
EcDENCLoadViewByArea and EcChartLoadViewByArea. The parameters are
• view Pointer to a view context
• products Array of product IDs
• nProducts Number of product IDs in array
• productsFlag Include (True) or exclude product IDs
• producerCodes Array of producer codes
• nProducerCodes Number of producer codes in array
• producerCodesFlag Include (True) or exclude producer codes

Chart Product Product ID Producer Code

ENC EC_DATA_PROD_ENC different
IENC EC_DATA_PROD_INLAND different
AIO EC_DATA_PROD_AIO 540 (GB) similar to UKHO
ENC
AML EC_DATA_PROD_AML_CLB different
EC_DATA_PROD_AML_ESB
EC_DATA_PROD_AML_LBO
EC_DATA_PROD_AML_MFF
EC_DATA_PROD_AML_RAL
EC_DATA_PROD_AML_SBO
EC_DATA_PROD_AML30
DNC EC_DATA_PROD_DNC 40003
TOD0 EC_DATA_PROD_TOD0 40006
TOD1 EC_DATA_PROD_TOD1 40030

172
 EC2007 ECDIS Kernel Programming Guide

TOD2 EC_DATA_PROD_TOD2 40008

TOD4 EC_DATA_PROD_TOD4 40031
VMap EC_DATA_PROD_VMAP 40005
EC_DATA_PROD_VMAP1
EC_DATA_PROD_VMAP2
ARINC EC_DATA_PROD_ARINC 40070
Table 3: Chart Product Ids and Producer Codes

To display non ENC products in conjunction with the SevenCs world data set the producer
code filter can be used. The SevenCs producer code is 31868.
In any case the dictionaries and lookup tables of the non-ENC chart product have to be
merged to the existing ENC dictionaries and lookup tables.

Please note:
In case the function EcChartSetDisplaySelector is used for any kind of chart settings, the
non-ENC lookup tables must be merged whenever some value of the display selector has
been changed.

For more details about handling non-ENC chart products please refer to the chapter which
deals with the respective chart product.

9.1 Special Chart Display Technology

When different chart products shall be displayed in combination with other chart products
special features must be considered. It is for this special case that two technologies were
invented: Data Overlay and Data Displacement.
If any vector chart data shall be combined with raster charts only Data Overlay can be used.
The EC2007 ECDIS Kernel offers functions to systematically utilize both technologies and to
adapt them to the respective needs.

9.1.1 Data Overlay

Data Overlay means that some data products will superimpose others (e.g. normal ENCs or
raster charts) thus concealing them partly or wholly.
Only cells that have a usage value of 1024 or higher (value from the cell header) are
supposed to be overlay cells. By default only these cells are handled as overlay cells.
If the default behavior shall be changed a callback function must be installed with the
function EcDrawSetOverlayCheckCallback. This function installs a callback for external overlay
check functions and allows to define which cells are to be treated as "overlay" or "normal"
cells.
If the callback returns True the Kernel assumes that this cell contains data that will overlay
data from other cells.

173
EC2007 ECDIS Kernel Programming Guide

The following example shows how to define that AML MFF data shall be treated as overlay
cells.
Function Call:
EcDrawSetOverlayCheckCallback (view, overlayCheckCallback, userData);

Overlay function:
bool overlayCheckCallback (EcView *view, EcCellId cellId, void *userData)
{
char product[8];
EcCellGetHeaderInfo (cellId, EC_HDR_PRED, (caddr_t)product,
sizeof(product));
if(strncmp(product,"MF1.0",5) == 0 || strncmp(product,"MF2.1",5) == 0)
return true;
else
return false;
}

9.1.2 Data Displacement

Data Displacement means that parts of ENCs will be replaced by corresponding parts of
other data products. This technology can only be utilized with vector data. Certain types of
cells contain data that replace corresponding data of other cells in the same geographic
area. For instance a bathymetric ENC (bENC) only contains depth information (areas and
contours) that replaces other depth information from "normal" cells.
Other information from "normal" cells, for example navigational aids or traffic lanes, must
still be visible on top of the depth information. Therefore a simple overlay technique cannot
be used in this case. That is why SevenCs has introduced a special interlacing technique
called Data Displacement which replaces depth information on a layer-by-layer basis.
By default bENC, AML CLB and TOD chart products will be treated as displacement cells. If
the default behavior shall be changed a callback function must be installed with the function
EcChartSetDisplaceCheckCallback. This function installs a callback for external displace check
functions and can be used to determine which cells are to be treated as "displace" or
"normal" cells. If the callback returns True the Kernel assumes that this cell contains data
that will displace data from other cells.

9.2 Admiralty Information Overlay

The display of AIO on top of ENCs has to be enabled with the function
EcChartSetShowAdmiraltyOverlay. There is no need to load special object dictionaries or
lookup tables for the display.
Most of the AIO information refer to individual ENCs. In that case the AIO objects are only
displayed if the referred ENC is published by UKHO, i.e. has been imported as part of the
UKHO AVCS service.

174
 EC2007 ECDIS Kernel Programming Guide

9.3 InlandENC
InlandENCs or IENCs can be used in conjunction with ENCs without any problems because
they usually cover different areas and use additional usages.
To distinguish IENC from other S-57 based products the S-57 cell header fields PRSP and
PRED are used (see chapter 11.2.2).
The following table shows the S-57 value and the corresponding SENC values.

S-57 / PRSP S-57 / PRED SENC / Example

EC_HDR_PRED
10 1.02, 2.0, 2.1, 2.2 or “IN” + PRED “IN2.1”
2.3
Table 4: IENC PRSP and PRED values

Please note:
For the import of IENCs provided as S-57 files the S-57/S-63 Import Module is required.
For the display of IENC the IENC Display Module is required.

9.3.1 Dictionary Handling

The dictionaries for the IENC product are loaded with the function EcDictionaryReadModule.
The following example will load all the IENC 1.02 and the latest 2.x dictionaries in addition to
the standard ENC dictionaries (see chapter 6.4).
EcDictInfo *dictInfo;
UINT32 module = EC_MODULE_MAIN | EC_MODULE_INLAND;
if ((dictInfo = EcDictionaryReadModule(module, NULL)) == NULL)
{ /* error handling */ }

...

EcDictionaryFree(dictinfo);

9.3.2 IENC Installation

IENCs are usually provided as unprotected plain S-57 files, as S-57 Exchange Set or as
directENC packages. The S-63 protections schema is not applied to IENCs. Therefore the
standard functions EcDENCImportFile, EcDENCImportTree or EcDENCImportS57ExchangeSet can
be used to install the data in the DENC structure (see chapter 6.5.4). For the final conversion
EcDENCCheckUpdates and EcDENCApplyUpdates must be used (see chapter 6.5.10).

175
EC2007 ECDIS Kernel Programming Guide

9.3.3 IENC Display

IENC data are displayed using the same S-52 approach as ENCs, i.e. by lookup tables and
symbols.
The different IENC lookup tables have to be merged with the ENC lookup tables. This has to
be done after each call EcChartSetLookupTable. The next example shows how the lookup
tables are defined and later added and merged to the view context.
// defined by user
int lut = EC_LOOKUP_TRADITIONAL;

EcChartSetLookupTable(view, lut);

const char *lib7csStr = NULL;

char ltIenc102p[256], ltIenc102l[256], ltIenc102a[256];
char ltIenc2p[256], ltIenc2l[256], ltIenc2a[256];

if ((lib7csStr = EcKernelGetEnv("LIB_7CS")) == NULL)

{ /* error handling */ }

// define the lookup table files for IENC product

sprintf(ltIenc102p, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltIenc102l, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltIenc102a, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
if (lut == EC_LOOKUP_SIMPLIFIED)
sprintf(ltIenc2p, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
else
sprintf(ltIenc2p, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltIenc2l, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltIenc2a, "%s/lib/preslib4/lookup/[Link]", lib7csStr);

// add and merge the IENC 1.02 lookup tables

int ltIenc102 = EcChartAddLookupTable(view, ltIenc102p, ltIenc102l,
ltIenc102a);
if (ltIenc102 >= 0)
EcChartMergeLookupTable(view, ltIenc102);

// add and merge the IENC 2.x lookup tables

int ltIenc2 = EcChartAddLookupTable(view, ltIenc2p, ltIenc2l,
ltIenc2a);
if (ltIenc2 >= 0)
EcChartMergeLookupTable(view, ltIenc2);

9.3.4 Display of IENC Notice Marks

IENCs, especially in Europe, contain many notice marks. Within the chart view notice marks
can be displayed in three different ways, i.e. with
1. generic symbols
2. small sized real symbols

176
 EC2007 ECDIS Kernel Programming Guide

3. big real symbols

To switch between the different symbols the function EcRiverChartSetNoticeMarkMode can be
used. The possible parameters are EC_NOTICEMARK_GENERIC, EC_NOTICEMARK_BIG or
EC_NOTICEMARK_SMALL.
To show the real notice mark symbols in a pick window an extra view structure has to be
created for the pick window. With the picked notice mark feature the related symbol can be
queried with EcRiverChartGetNoticeMarkSymbol and displayed with EcDrawNTDrawSymbol.

9.4 Additional Military Layers (AML)

Please note:
For use and display of AML the S-57/S-63 Import Module and the AML Display Module is
required.

AML product specifications were developed by the NATO in conjunction with the UKHO. For
detailed information please refer to the document AML_Handbook_UKHO which can be
downloaded from the UKHO homepage. AML products are based on the S-57 format, i.e. the
data structure and model. They may contain ENC objects but mostly contain specific AML
objects. Some of the AML chart products serve as an overlay to ENCs or other AML chart
products.
To distinguish AML from other S-57 based products the S-57 cell header fields PRSP and
PRED are used (see chapter 11.2.2).
The following table shows the different S-57 values and their corresponding SENC values.

AML Product S-57 / PRSP S-57 / PRED SENC / EC_HDR_PRED Example

MFF 51 1.0 or 2.1 “MF” + PRED “MF2.1”
RAL 52 1.0 or 2.1 “RA” + PRED “RA2.1”
LBO 53 1.0 or 2.1 “LB” + PRED “LB2.1”
CLB 54 1.0 or 2.1 “CL” + PRED “CL2.1”
ESB 55 1.0 or 2.1 “ES” + PRED “ES2.1”
SBO 56 1.0 or 2.1 “SB” + PRED “SB2.1”
AML 3.0 57 3.0 “AM3.0”
Table 5: AML PRSP and PRED Values

177
EC2007 ECDIS Kernel Programming Guide

9.4.1 Dictionary Handling

The dictionaries for the different AML products are loaded with the function
EcDictionaryReadModule. The following example will load all AML dictionaries in addition to
the standard ENC dictionaries (see chapter 6.4).
EcDictInfo *dictInfo;
UINT32 module = EC_MODULE_MAIN | EC_MODULE_AML;
if ((dictInfo = EcDictionaryReadModule(module, NULL)) == NULL)
{ /* error handling */ }

...

EcDictionaryFree(dictinfo);

If using AML 3.0 data the AML 30 dictionaries AML301ENO.7DI and AML301ENA.7DI have to be
merged to the existing dictionaries with EcDictionaryMergeExt.

9.4.2 AML Chart Installation

AML charts are usually provided as single files or as S-57 Exchange Sets. Therefore the
standard functions EcDENCImportFile, EcDENCImportTree or EcDENCImportS57ExchangeSet can
be used to install the data in the DENC structure (see chapter 6.5.4). For the final conversion
EcDENCCheckUpdates and EcDENCApplyUpdates must be used (see chapter 6.5.10).
During the conversion the AML usages are converted into the following SENC usages:

S-57 / INTU SENC / EC_HDR_INTU

100 EC_OVERLAY
101 EC_OVERLAY | EC_OVERVIEW
102 EC_OVERLAY | EC_OVERVIEW
103 EC_OVERLAY | EC_OVERVIEW
104 EC_OVERLAY | EC_GENERAL
105 EC_OVERLAY | EC_COASTAL
106 EC_OVERLAY | EC_APPROACH
107 EC_OVERLAY | EC_HARBOR
108 EC_OVERLAY | EC_BERTHING
109 EC_OVERLAY | EC_RIVER
Table 6: AML Usages

178
 EC2007 ECDIS Kernel Programming Guide

9.4.3 AML Chart Loading and Display

AML data are displayed using the same S-52 approach as ENCs, i.e. by lookup tables and
symbols.
The different AML lookup tables have to be merged with the ENC lookup tables. This has to
be done after each call EcChartSetLookupTable.
The next example shows how the lookup tables are defined and later added and merged to
the view context. Unfortunately
const char *lib7csStr = NULL;
char ltClbA[256], ltClbL[256], ltClbP[256];
char ltEsbA[256], ltEsbL[256], ltEsbP[256];
char ltLboA[256], ltLboL[256], ltLboP[256];
char ltMffA[256], ltMffL[256], ltMffP[256];
char ltRalA[256], ltRalL[256], ltRalP[256];
char ltSboA[256], ltSboL[256], ltSboP[256];
char ltClb2A[256], ltClb2L[256], ltClb2P[256];
char ltEsb2A[256], ltEsb2L[256], ltEsb2P[256];
char ltLbo2A[256], ltLbo2L[256], ltLbo2P[256];
char ltMff2A[256], ltMff2L[256], ltMff2P[256];
char ltRal2A[256], ltRal2L[256], ltRal2P[256];
char ltSbo2A[256], ltSbo2L[256], ltSbo2P[256];

if ((lib7csStr = EcKernelGetEnv("LIB_7CS")) == NULL)

{ /* error handling */ }

// initially define the lookup table files for AML products

sprintf(ltClbP, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltClbL, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltClbA, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltEsbP, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltEsbL, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltEsbA, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltLboP, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltLboL, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltLboA, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltMffP, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltMffL, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltMffA, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltRalP, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltRalL, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltRalA, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltSboP, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltSboL, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltSboA, "%s/lib/preslib4/lookup/[Link]", lib7csStr);

sprintf(ltClb2P, "%s/lib/preslib4/lookup/[Link]", lib7csStr);

sprintf(ltClb2L, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltClb2A, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltEsb2P, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltEsb2L, "%s/lib/preslib4/lookup/[Link]", lib7csStr);

179
EC2007 ECDIS Kernel Programming Guide

sprintf(ltEsb2A, "%s/lib/preslib4/lookup/[Link]", lib7csStr);

sprintf(ltLbo2P, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltLbo2L, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltLbo2A, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltMff2P, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltMff2L, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltMff2A, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltRal2P, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltRal2L, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltRal2A, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltSbo2P, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltSbo2L, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltSbo2A, "%s/lib/preslib4/lookup/[Link]", lib7csStr);

...

/* whenever the ENC lookup tables were set with EcChartSetLookupTable

add and merge the AML CLB lookup tables */

int ltClb = EcChartAddLookupTable(view, ltClbP, ltClbL, ltClbA);

if (ltClb >= 0)
EcChartMergeLookupTable(view, ltClb);

// do the same for the other five AML 1.0 and six AML 2.1 products

When AML data shall be displayed in SENC format in combination with other vector data
some special features must be considered. It is for this special case that the two chart display
technologies Data Overlay and Data Displacement were developed (see chapter 9.1).
By default AML LBO, RAL and SBO will be treated as overlay cells, AML CLB as displacement
cells and AML ESB and MFF as “normal” cells. If that behavior shall be changed, callback
functions must be introduced.
If AML data shall be combined with raster charts only Data Overlay can be used.

9.5 DNC, VMap, TOD

There are three products which are based on the VPF format, i.e. DNC, VMap and TOD. For
details please refer to the document EC2007_BackgroundInformation.

Please note:
For the import of VPF data the VPF Import Module is required. For the display of VPF
data the DNC/TOD and/or the VMap Display Module are required.

The function set EC27_DNC is used to process DNC, VMAP and TOD data. Thus, whenever in
the following text DNC is mentioned the functions described can be applied to VMAP and
TOD data as well.

180
 EC2007 ECDIS Kernel Programming Guide

9.5.1 Dictionary Handling

The dictionaries for DNC and VMap are loaded with the function EcDictionaryReadModule.
The following example will load the DNC and VMap dictionaries in addition to the standard
ENC dictionaries.
EcDictInfo *dictInfo;
UINT32 module = EC_MODULE_MAIN | EC_MODULE_DNC | EC_MODULE_VMAP;
if ((dictInfo = EcDictionaryReadModule(module, NULL)) == NULL)
{ /* error handling */ }

...

EcDictionaryFree(dictinfo);

Please note:
The TOD and MATT dictionaries are loaded together with the DNC dictionaries, i.e. by the
module value EC_MODULE_DNC.

9.5.2 VPF Import

DNC data are provided in databases, each of which consists of several libraries which in turn
consist of coverages, divided in tiles.
According to the structure the functions EcDNCOpenDatabase, EcDNCOpenLibrary and
EcDNCReadTile(s) are used to import a DNC database. Finally each tile is converted into a
SENC cell.
One parameter EcDNCOpenDatabase takes is the root path of the DNC database. On UNIX
systems make sure that all files and directories under the dbPath are in lower cases. Refer to
the documentation of the mount command of your system to find out how this is achieved.
To obtain a list of available libraries and tiles use EcDNCDatabaseGetLibraries or
EcDNCLibraryGetTiles respectively.

Please note:
SevenCs highly recommends to store S-57 and DNC data in different DENC structures.

After the desired tiles have been imported the library and the database have to be closed
using EcDNCCloseLibrary and EcDNCCloseDatabase. The name of the SENC file that results from
the import can be obtained by calling EcDNCGetSENCName.
For an example of reading DNC data please refer to the example program dncto7cb.
Once the DNC tile has been successfully imported the resulting SENC cell may be in turn
imported into a DENC structure using EcDENCImportFile, or may be used with other Kernel
functions.

181
EC2007 ECDIS Kernel Programming Guide

Please note:
The DNC features and attributes are not converted into ENC objects by EcDNCReadTile(s)
but into FACC codes.

The DNC coding is stored in the SENC without changes. Software that explicitly handles ENC
objects or that expects certain S-57 objects to be present in a SENC should be changed to
work with the corresponding DNC FACC features or to give a warning if working on DNC
based SENCs.
Once the DNC data have been imported into the SENC database all ECDIS Kernel functions
can be used as usual to access the data (see chapter 11).
The usage and compilation scale are assigned depending on the VPF product or tile type.

Product Library Name Usage Compilation Scale

DNC B* EC_OVERVIEW 7.500.000
G* EC_GENERAL 500.000
K* EC_ COASTAL 150.000
A* EC_APPROACH 50.000
H* EC_HARBOUR 12.500
VMap0 EC_GENERAL
VMap1 EC_COASTAL

9.5.3 DNC Updating

For the update of DNC the National Geospatial-Intelligence Agency (NGA) provides a special
software patch which is available for Windows but not for Linux. The software is delivered
with the EC2007 ECDIS Kernel and is located in %EC2007DIR%\contrib\VDU. For the use of the
software please refer to the readme file in the same directory.

9.5.4 VPF Chart Display

For the display of DNC, VMap or TOD there are two possibilities, the original GeoSym or an
enhanced symbolization, based on the S-52 approach of lookup tables and rules.

[Link] S-52 Symbolization

Please note:
SevenCs highly recommends to handle S-57 and VPF data in different view contexts.

The default display is based on the S-52 approach, i.e. there are lookup tables and symbols
for each VPF product. The DNC and/or VMap and/or TOD lookup tables have to be merged
to the mayor ENC lookup tables. This has to be done after each call EcChartSetLookupTable.

182
 EC2007 ECDIS Kernel Programming Guide

The next example shows how the lookup tables are defined and later added and merged to
the view context. In the case VMap1 or TOD data shall be displayed the respective lookup
tables have to be merged accordingly.
const char *lib7csStr = NULL;
char ltDncPs[256], ltDncLs[256], ltDncAs[256];
char ltDncPt[256], ltDncLt[256], ltDncAt[256];
char ltVmap0P[256], ltVmap0L[256], ltVmap0A[256];

if ((lib7csStr = EcKernelGetEnv("LIB_7CS")) == NULL)

{ /* error handling */ }

// define the lookup table files for DNC, simplified

sprintf(ltDncPs, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltDncLs, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltDncAs, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
// define the lookup table files for DNC, traditional
sprintf(ltDncPt, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltDncLt, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltDncAt, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
// define the lookup table files for VMap0
sprintf(ltVmap0P, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltVmap0L, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltVmap0A, "%s/lib/preslib4/lookup/[Link]", lib7csStr);

...

// set the display of ENC to 'Traditional'

EcChartSetLookupTable(view, EC_LOOKUP_TRADITIONAL);

// add and merge the lookup tables for DNC, traditional

int ltDnc = EcChartAddLookupTable( view, ltDncPt, ltDncLt, ltDncAt);
if (ltDnc >= 0)
EcChartMergeLookupTable(view, ltDnc);

// add and merge the lookup tables for Vmap0

int ltVmap0 = EcChartAddLookupTable(view, ltVmap0P, ltVmap0L,
ltVmap0A);
if (ltVmap0 >= 0)
EcChartMergeLookupTable(view, ltVmap0);

[Link] GeoSym Handling

In the case VPF data shall be displayed using the GeoSym the functions EcGeoSymCreate and
EcChartSetGeoSym have to be used. In addition there functions to modify the GeoSym
display. For details please refer to the Function Reference.
EcGeoSym *geoSymLib = EcGeoSymCreate( "C:/MyECDIS/lib/GeoSym", NULL );
if(geoSymLib != NULL)
EcChartSetGeoSym(view, geoSymLib);

183
EC2007 ECDIS Kernel Programming Guide

Please note:
In case GeoSym is used EcDrawNTInitializeExt must not be called with alpha blending
enabled.

9.5.5 Navigational Functions

For anti-grounding or route checking the special DNC danger catalogue [Link] must be
loaded (see chapter 7.3) and used with EcMonitorCheckGuardZone, EcRouteCheck or
EcQueryIsObjectDangerous.

9.6 ARINC
ARINC charts provide an aviation overlay for other charts, e.g. ENC. Before they can be used
within EC2007 ECDIS Kernel they have to be imported to the DENC database by means of the
function EcARINCDencImport. During import the SENC usage will be set to EC_OVERLAY.
To distinguish ARINC data from other S-57 based products the S-57 cell header fields PRSP
and PRED are used (see chapter 11.2.2).
The following table shows the S-57 value and the corresponding SENC values.

S-57 / PRSP S-57 / PRED SENC / EC_HDR_PRED Example

70 1.0 “AV” + PRED “AV1.0”
Table 7: ARINC PRSP and PRED values

Please note:
The ARINC functionality is not available for Red Hat 5 and OpenSUSE 11.
For the import of IENCs provided as S-57 files the S-57/S-63 Import Module is required.
For the display of ARINC the ARINC Module is required.

9.6.1 Dictionary Handling

The dictionaries for the ARINC product are loaded with the function EcDictionaryReadModule.
The following example will load the ARINC 1.0 dictionaries in addition to the standard ENC
dictionaries (see chapter 6.4).
EcDictInfo *dictInfo;
UINT32 module = EC_MODULE_MAIN | EC_MODULE_ARINC;
if ((dictInfo = EcDictionaryReadModule(module, NULL)) == NULL)
{ /* error handling */ }

...

184
 EC2007 ECDIS Kernel Programming Guide

EcDictionaryFree(dictinfo);

9.6.2 ARINC Display

ARINC data are displayed using the same S-52 approach as ENCs, i.e. by lookup tables and
symbols.
The different ARINC lookup tables have to be merged with the ENC lookup tables. This has to
be done after each call EcChartSetLookupTable. The next example shows how the lookup
tables are defined and later added and merged to the view context.
// defined by user
int lut = EC_LOOKUP_TRADITIONAL;

EcChartSetLookupTable(view, lut);

const char *lib7csStr = NULL;

char ltarincp[256], ltarincl [256], ltarinca [256];

if ((lib7csStr = EcKernelGetEnv("LIB_7CS")) == NULL)

{ /* error handling */ }

// define the lookup table files for IENC product

sprintf(ltarincp, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltarincl, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltarinca, "%s/lib/preslib4/lookup/[Link]", lib7csStr);

// add and merge the IENC 1.02 lookup tables

int ltArinc = EcChartAddLookupTable(view, ltarincp, ltarincl,
ltarinca);
if (ltArinc >= 0)
EcChartMergeLookupTable(view, ltArinc);

9.7 MIL-2525
The MIL-2525 Standard is a pure display standard. To be able to display not only symbols on
the screen SevenCs developed an MIL-2525 product specification and object catalogue as
well. That means that the display of MIL-2525 symbols follows the same rules as for the
display of other S-57 based products, i.e.
• a MIL-2525 SENC has to be created and
• the MIL-2525 SENC has to be filled with objects

185
EC2007 ECDIS Kernel Programming Guide

9.7.1 Installation
The MIL-2525 symbols are only provided on demand as an independent setup or archive. It
will be installed or has to be extracted in the library directory of the EC2007 ECDIS Kernel
which is defined with the environment variable “LIB_7CS”.

Path MIL 2525 files Remark

$LIB_7CS\lib\preslib4\colour [Link]
Colour definitions. For
Windows the original
file will be copied
before, for Linux a copy
has to be created
manually.
$LIB_7CS\lib\preslib4\sym\rah ------[Link][l][m]
MIL-2525 symbols
$LIB_7CS\lib\preslib4\sym\ral -[Link][l][m]
$LIB_7CS\lib\preslib4\sym\ram ......

9.7.2 Dictionary Handling

The dictionaries for MIL-2525 are loaded with the function EcDictionaryReadModule. The
following example will load the MIL-2525 dictionaries in addition to the standard ENC
dictionaries.
EcDictInfo *dictInfo;
UINT32 module = EC_MODULE_MAIN | EC_MODULE_MIL_2525;
if ((dictInfo = EcDictionaryReadModule(module, NULL)) == NULL)
{ /* error handling */ }

...

EcDictionaryFree(dictinfo);

9.7.3 Lookup Table Handling

MIL-2525 data are displayed using the same S-52 approach as ENCs, i.e. by lookup tables and
symbols.
The MIL-2525 lookup tables have to be merged with the ENC lookup tables. This has to be
done after each call EcChartSetLookupTable.
The next example shows how the lookup tables are defined and later added and merged to
the view context.
const char *lib7csStr = NULL;
char ltM2525A[256], ltM2525L[256], ltM2525P[256];

if ((lib7csStr = EcKernelGetEnv("LIB_7CS")) == NULL)

{ /* error handling */ }

// define the lookup table files for AML products

186
 EC2007 ECDIS Kernel Programming Guide

sprintf(ltM2525P, "%s/lib/preslib4/lookup/[Link]", lib7csStr);

sprintf(ltM2525L, "%s/lib/preslib4/lookup/[Link]", lib7csStr);
sprintf(ltM2525A, "%s/lib/preslib4/lookup/[Link]", lib7csStr);

...

// set the display of ENC to 'Traditional'

EcChartSetLookupTable(view, EC_LOOKUP_TRADITIONAL);

// add and merge the AML CLB lookup tables

int ltM2525 = EcChartAddLookupTable(view, ltM2525P, ltM2525L,
ltM2525A);
if (ltM2525 >= 0)
EcChartMergeLookupTable(view, ltM2525);

9.7.4 Creating a New MIL-2525 Data Set

To create a new MIL-2525 data set you have to set certain data set meta information, after
the data set has been created with the default values for an ENC (see chapter 11.4).
char cellFileName[256];
EcCellId cellId;

strcpy (cellFileName, "./0_MMIL25.7CB");

EcCellCreate(cellFileName,4096);
cellId = EcCellMap(cellFileName, EC_ACCESSWRITE, 0);
if (cellId == EC_NOCELLID)
// error handling
else
{
int usage = EC_OVERLAY;
EcCellSetHeaderInfo(cellId, EC_HDR_INTU, (caddr_t)&usage);
EcCellSetHeaderInfo(cellId, EC_HDR_PRED, (caddr_t)"M2B.2");
}

...

EcCellUnmap(cellId);

In order to create MIL-2525 data by means of a graphical user interface the SevenCs ENC
Designer, an editing tool for S-57 data products, can be used.

9.7.5 Example Data

The example data contain different data sets which cover all UIE objects.

7CMADIND.7CB Examples for additional indicators, e.g. echelon and mobility

7CMAFILT.7CB Affiliation overview

187
EC2007 ECDIS Kernel Programming Guide

7CMAIR0[1-3].7CB Air tracks

7CMEXERC.7CB Exercise amplifying descriptor
7CMGRD0[1-13].7CB Ground tracks
7CMSBST1.7CB Subsurface tracks
7CMSOF01.7CB Special operation forces (SOF)
7CMSSFT1/2.7CB Sea surface tracks

9.7.6 Object Class and Attributes

Object class:
uneqin Unit, equipment and installation object
Attributes:
catuei Category of unit, equipment or installation enumeration
1 Space track
2 Air track
3 Ground track unit
4 Ground track equipment
5 Ground track installation
6 Sea surface track
7 Subsurface track
8 Special operations forces (SOF) unit
afiltn Affiliation enumeration
1 Friend
2 Neutral
3 Hostile
4 Assumed friend
5 Suspect
6 Pending
echind Echelon indicator enumeration
1 Team/Crew
2 Squad
3 Section

188
 EC2007 ECDIS Kernel Programming Guide

4 Platoon
5 Company
6 Bataillon
7 Regiment
8 Brigade
9 Division
10 Corps
11 Army
12 Armygroup
13 Region
mobind Mobile Equipment Indicator enumeration
1 Wheeled (limited cross country)
2 Wheeled (cross country)
3 Tracked
4 Wheeled and tracked combination
5 Towed
6 Railway
7 Over snow
8 Sled
9 Pack animals
10 Barge
11 Amphibious
auxind Auxilliary equipment indicator enumeration
1 Feint
2 Task force
3 Headquarter
examde Exercise amplifying descriptor enumeration
1 Friend
2 Neutral
3 Assumed friend
4 Joker
5 Faker
6 Pending

189
EC2007 ECDIS Kernel Programming Guide

addind Additional indicators list

1 Feint
2 Task force
3 Headquarter

9.8 bathymetric ENC (bENC)

Bathymetric ENCs only contain depth information, i.e. depth areas, depth contours and
soundings. They are used in conjunction with ENCs, i.e. they have the role of an optional
bathymetric complement to official ENCs.
In addition to the bENC function EcChartGetBathymetricMode the high level function
EcDraw[NT][X11]DrawChart has to be split into seperated low level functions. For details
please refer to the example program showBENC.

9.9 User-Defined Chart Objects

For the display of customer’s objects there are three sets of files necessary
1. Dictionaries for objects and attributes
2. Lookup tables for point, line and area objects
3. Symbol files for points, line styles and area fill pattern
An example data set containing user-defined objects and the required dictionaries and
lookup tables are located in $EC2007/data/Samle/myObjects.

9.9.1 User-Defined Dictionaries

Similar to the dictionaries for ENCs or other S-57 chart products the dictionaries containing
the user-defined objects and attributes have to be created.
SevenCs provides examples dictionaries, i.e.
• For object dictionary: MYOBJCAT.7DI
• For attribute dictionary: MYATRCAT.7DI

[Link] Format
The format of the object dictionary is as follows:
*"MKEY","0x00000800"
*"PKEY","1"
*"PROD","Customer object classes"
*"PRDV","1.0"
*"LANG","EN"
*"DOCV","1.0"
*"_EOH_"
"myobjt","65000","G",""

190
 EC2007 ECDIS Kernel Programming Guide

"My Object"
"catmyo;agemyo;OBJNAM;SCAMIN;"
"INFORM;NINFOM;"
"SORDAT;SORIND;"
"Point;Line;Area;"
""
""
""
""
""
""
""
""

Each entry of a feature object consists of 14 rows.

Row Entry Description

1 "myobjt" Feature acronym (six characters, lower
case)
"65000" Feature code (should be between 65000
and 65535)
"G" Feature type. G = Geo, M = Meta
"" Empty
2 "My Object" Feature full name
3 "catmyo;agemyo;OBJNAM;SCAMIN;" Attributes of attribute set A
4 "INFORM;NINFOM;" Attributes of attribute set B
5 "SORDAT;SORIND;" Attributes of attribute set C
6 "Point;Line;Area;" Geometry Type
7-14 “” May all be left empty
The format of the attribute dictionary is as follows:
*"MKEY","0x00000800"
*"PKEY","1"
*"PROD","Customer attributes"
*"PRDV","1.0"
*"LANG","EN"
*"DOCV","1.0"
*"_EOH_"
"catmyo","65000","F",""
"Category of my object"
"useful"
"senseless"
"\"
""
""
""
""

191
EC2007 ECDIS Kernel Programming Guide

""
"E"
""
""
""
"agemyo","65001","F",""
"Age of my object"
"\"
""
""
""
""
""
"I"
""
""
""

Each entry of an attribute consists of at least12 rows.

Row Entry Description

1 "catmyo" Attribute acronym (six character long, small case)
"65000" Attribute code (should be between 65000 and
65535)
"F" Attribute type. F = Feature, S = Spatial
"" Empty
2 "Category of my Attribute long name
object"
3 to n “great” Attribute values:
for enumeration or list attributes for each value one
line, last row must be "\"
for float, integer, or string attributes only one “\”
n+1 to "" Empty
n+5
n+6 "E" Attribute type:
E = enumeration, L = list, F = float, I = integer,
A = formatted string, S = free text
n+7 to "" Empty
n+9

[Link] Implementation
After the main dictionaries for ENCs have been read with EcDictionaryReadModule, the user-
defined dictionaries have to be merged.
EcDictInfo *dictInfo;

192
 EC2007 ECDIS Kernel Programming Guide

EcDictInfo *myDictInfo;

// read the object and attribute dictionaries

if (myDictInfo = EcDictionaryReadModule(EC_MODULE_MAIN, NULL)) == NULL)
{ /* error handling */ }

// merge the user defined dictionaries

myDictInfo = EcDictionaryMergeExt("[MYPATH]/MYOBJCAT.7DI",
"[MYPATH]/MYATRCAT.7DI",
dictInfo, true, NULL);
if (myDictInfo == NULL)
//error handling
else
dictInfo = myDictInfo;

9.9.2 User-Defined Lookup Tables

Similar to the lookup tables for ENCs or other S-57 chart products the lookup tables
containing symbol instructions for the user-defined objects and attributes have to be
created.
SevenCs provides examples lookup tables, i.e.
• For point lookup table: [Link]
• For line lookup table: [Link]
• For area lookup table: [Link]

[Link] Format
The format of the lookup tables is as follows:
"myobjt","","SY(POSGEN04)","80","O","OTHER","32250"

Each entry of a lookup table consists of 7 entries:

No Entry Description
1 “myobjt” Feature acronym
2 “catmyo1|” Attribute entry (name, value, delimiter “|”)
3 “SY(POSGEN04)” Symbol instruction (SY = point symbol, LS = simple line style, LC =
complex line style, AC = area colour fill, AP = area pattern, CS =
conditional symbology, TX = text, TE = formatted test)
4 “80” Display Layer (1 to 100)
5 “O” Radar flay (O = over radar, S = Suppressed by radar)
6 “OTHER” Display Category (BASE, STANDARD, OTHER)
7 “32250” Viewing Group
For a detailed description of the different symbol instructions please refer to the S-52
Presentation Standard.
193
EC2007 ECDIS Kernel Programming Guide

[Link] Implementation
Whenever the major lookup tables have been defined with EcChartSetLookupTable the user-
defined lookup tables have to be merged afterwards.
int myLut;

myLut = EcChartAddLookupTable( view, "[MYPATH]/[Link]",

"[MYPATH]/[Link]",
"[MYPATH]/[Link]");
if (myLut >= 0)
EcChartMergeLookupTable(view, myLut);
else
//error handling

9.9.3 Symbols, Line Styles and Area Fills

Similar to the symbols, line styles and area fill pattern for ENCs or other S-57 chart products
the symbols for the user-defined objects have to be created or to be selected from the
existing ones.
The symbol files have to be copied to the respective directories, i.e.
• For points (vector): $LIB_7CS\lib\preslib4\sym
• For points (raster): $LIB_7CS\lib\preslib4\sym\ra[h][l][m]
• For line styles: $LIB_7CS\lib\preslib4\lin
• For area fill pattern: $LIB_7CS\lib\preslib4\pat
• For a detailed description of the file formats please refer to the S-52 Presentation
Standard.

9.10 Raster Charts

Besides ARCS (see chapter 5.4) the EC2007 ECDIS Kernel supports the display of BSB and
GeoTiff data.

9.10.1 BSB

Please note:
The core DLLs are currently available only for Windows (Win32). On Unix systems the
EcBSB... functions will return error codes.

The core routines are included in a set of separate DLLs, whereas the Kernel provides an
interface compatible with other function sets.

194
 EC2007 ECDIS Kernel Programming Guide

Before BSB charts can be used the core DLL [Link] must be loaded by calling
EcBSBInitialize. This function tries to locate the DLL in the specified search path. If this fails,
subsequent calls to other EcBSB… functions will also fail. When the BSB functions are no
longer used EcBSBEnd should be called to unload the DLL and free internal resources. The
core DLLs are available from SevenCs on request.
All EcBSB... functions set error codes on failure.
EcBSBGetLastError returns the error number and the corresponding message text for the
EcBSB... function that has been last called. The message text is particularly useful in case the
function EcBSBLoadChart has returned a non-zero value.
A BSB raster chart consists of a number of separate files. The file names correspond to the
chart number, whereas the file extensions differ according to the content.
EcBSBLoadChart loads the specified BSB chart. The parameter fName must specify the .KAP
file of the chart. If the chart is going to be displayed the parameter mode must be set to
eOpenAllInfo.
If only information about the chart is going to be queried the parameter mode may be set to
eOpenQuick. This will cause the chart to be loaded faster.
The members of the structure bsbInfo are filled in by the function EcBSBLoadChart, too. They
may be checked but must never directly be changed by the application.
When the chart is no longer needed it should be unloaded by calling EcBSBUnloadChart.
If the function EcBSBLoadChart returns a negative value the chart could not be loaded. If it
returns a positive value the chart could be loaded but the user should be informed by
displaying the warning message returned by EcBSBGetLastError.
If an update path has been specified by calling EcBSBSetUpdatePath the function
EcBSBLoadChart searches it for update patches belonging to the chart which shall be loaded.
If the currently loaded chart is no longer needed EcBSBUnloadChart should be called to
unload the chart and free system resources.
Once a chart has been loaded geographic coordinates can be transformed into screen
coordinates and vice versa by using one or more of the following functions:
• EcBSBImageToLatLon
• EcBSBXyToLatLon
• EcBSBImageToWGS84
• EcBSBXyToWGS84
• EcBSBLatLonToImage
• EcBSBLatLonToXy
• EcBSBWGS84ToImage
• EcBSBWGS84ToXy
• EcBSBGetWGS84Shift
Each BSB chart contains at least one default colour palette. However, other palettes may
exist to support night-time viewing of the chart.

195
EC2007 ECDIS Kernel Programming Guide

EcBSBGetPaletteFromChart returns a pointer to a palette structure that contains the colour

definitions used by the currently loaded chart.
Other than the default palette are not necessarily supported for a particular chart. In this
case NULL is returned.
The parameter palType may be set to one of the following values:
• ePalDefault: Default palette. Always available.
• ePalDayTime: Bright daylight palette. Optional.
• ePalDusk: Dusk and dark daylight. Optional.
• ePalNightTime: Colours for night conditions. Optional.
• ePalRed: Shades of red for night conditions. Optional.
• ePalGray: Shades of grey. Optional.
Two functions are available for chart drawing. One of them returns the unscaled image,
whereas the other allows scaling of the chart.
EcBSBGetChartImage draws the currently loaded chart into the specified destination device
context. The device context must have a sufficiently large DDB selected beforehand. If
chartColors is set to NULL the default palette of the chart will be used. Otherwise the colours
from the specified palette structure will be deployed. The chart is drawn unscaled, i.e. one
image pixel will correspond to one pixel in the destination device context.
EcBSBDrawChart draws the currently loaded chart into the specified destination device
context. The device context must have a sufficiently large DDB selected before. If chartColors
is set to NULL the default palette of the chart will be used. Otherwise the colours from the
specified palette structure will be deployed. The chart is centered on the specified
geographic position and scaled to the specified height of the destination rectangle. If range
is set to less or equal 0 the chart will be drawn unscaled, i.e. one image pixel will correspond
to one pixel in the destination device context.
Information on the loaded chart can be retrieved by either using the following high level
functions or by evaluating the members of the structure EcBSBChartInfo.
EcBSBGetImageSize returns the horizontal and vertical image size of the currently loaded
chart.
EcBSBGetChartScale returns the chart scale of the currently loaded chart. Note that the chart
scale may differ from the display scale. The display scale should always be calculated by the
application based on the actual screen's pixel size.
EcBSBGetChartCoverage returns a polygon that defines the navigable part of the currently
loaded chart. The positions are in chart local datum. The function allocates memory to the
latitude/longitude arrays. If the return value is greater 0 the application must release the
memory by calling EcFree.
EcBSBGetChartTitle returns the title, number, scale and approximated center position of the
currently loaded chart. Any of the output parameters may be set to NULL if the information
is not needed.
To facilitate finding a specific chart from the list of all installed charts catalogue functions are
provided that support administration and search.

196
 EC2007 ECDIS Kernel Programming Guide

EcBSBUpdateCatalogue adds the specified chart to the chart catalogue. If the catalogue
already contains a chart with the same name that chart will be replaced.
The parameter catPath specifies either a file name or a directory. In the latter case the
directory will be searched for the default catalogue CATALOG.7CC. If the specified catalogue
does not exist it will be created. The parameter chartName must specify the full path of a
chart file with the extension .KAP.
EcBSBCreateCatalogue creates a new chart catalogue. The parameter catPath specifies either
a file name or a directory. In the latter case the default catalogue CATALOG.7CC will be
created. The parameter chartName must specify the path to chart files with the extension
.KAP. Subdirectories of this path will also be searched for valid chart files.
EcBSBFindChart searches a chart catalogue for charts that intersect the specified polygon. If
the polygon has only one coordinate it will be taken for a point location. If it has more than 2
coordinates and the first and the last coordinate are the same it will be taken for an area,
otherwise for a line.
The parameter catPath specifies either a file name or a directory. In the latter case the
default catalogue CATALOG.7CC will be used. If coor is NULL or nCoor is less or equal 0 all
charts from the catalogue will be returned.
The function allocates memory to the return array. If the returned number of entries in the
array is greater 0 the application must release the memory by calling EcFree.
EcBSBSetImageCache enables caching of the chart image. The cache needs several megabytes
of memory, therefore it is disabled by default.

Please note:
BSB functions are not thread-safe. If more than one BSB chart must be used at a time the
same thread should carry out all the chart handling.

For an example of an application of these functions please refer to the example program
bsbtest.

9.10.2 GeoTiff
The EC2007 ECDIS Kernel provides a function which extracts the meta information of a
GeoTiff image. These are needed for the transformation of the GeoTiff coordinates into
geographic coordinates Lat/Lon which are then used further for the calculation of the
extension of the view.
The function EcGetGeoTiffInfo takes following parameters:
• filename Name and path of the file
• index Index of the desired image in the file
• geoTiffInfo Structure of type EcGeoTiffInfo which contains all extracted informations
The member datum and projection of the returned structure geoTiffInfo can be used to set
the datum and projection with the functions EcDrawSetDatum and EcDrawSetProjectionExt. If
this information is not given in the GeoTiff file the member transformation can be used with
the function EcDrawSetTransformation.
197
EC2007 ECDIS Kernel Programming Guide

For an example of an application of these functions please refer to the example program
geoTiffTest.
The drawing of the GeoTiff image has to be implemented by means of any publicly available
image rendering software, e.g. libTiff or Qt.

198
 EC2007 ECDIS Kernel Programming Guide

10 Dictionary Access
After the object dictionary has been read with EcDictionaryReadModule (see chapter 6.4)
the content of the dictionary can be read with several functions which are described in this
chapter.
Each object class or attribute is defined by two keys, a numeric code and an alphanumeric
token of six characters length (acronym). The following functions are used to retrieve related
keys:
• EcDictionaryGetObjectToken
• EcDictionaryGetAttributeToken
• EcDictionaryGetObjectCode
• EcDictionaryGetAttributeCode
The return value of all following functions can be
• EC_DICT_OK on success
• EC_DICT_NOTFOUND object class or attribute is not in the given dictionary
• EC_DICT_ERROR on failure
The functions EcDictionaryGetObjectToken and EcDictionaryGetAttributeToken take the
following parameters:
• dictInfo Pointer to the dictionary context
• code Given object class / attribute numeric code
• token Returned object class / attribute alphanumeric token
These two functions search the given dictionary context for the object class or attribute
specified by its numeric code, and then return its acronym in the parameter token which is a
variable of the structure EcClassToken or EcAttributeToken respectively.
The functions EcDictionaryGetObjectCode and EcDictionaryGetAttributeCode take the following
parameters:
• dictInfo Pointer to the dictionary context
• token Given object class / attribute alphanumeric token
• code Returned object class / attribute numeric code
These two functions search the given dictionary context for the object class or attribute
specified by its acronym and then return its numeric code in the parameter code.
To check whether an object class or attribute given by its alphanumeric token exists in a
dictionary context the functions EcDictionaryObjectKnown and EcDictionaryAttributeKnown are
available, too. These functions take the following parameters:
• dictInfo Pointer to the dictionary context
• token Given object class / attribute alphanumeric token
Since the object class or attribute acronyms have a length of only six characters it is
sometimes helpful to have the full name to identify the object class or attribute.

199
EC2007 ECDIS Kernel Programming Guide

The functions EcDictionaryTranslateObjectToken and EcDictionaryTranslateAttributeToken

retrieve the full name of the object class or attribute specified by its acronym, respectively.
The parameters are:
• dictInfo Pointer to the dictionary context
• token Given object class / attribute alphanumeric token
• buffer Pointer to the result string
• bufferlen Size of buffer
In addition the function EcDictionaryTranslateAttributeValue translates the numeric value of
an attribute of type list or enumeration into its human-readable definition text. The
parameters are:
• dictInfo Pointer to the dictionary context
• attrCode Concatenation of attribute token and value code
• buffer Pointer to the result string
• bufferlen Size of buffer
The function EcDictionaryGetObjectAttributes queries the attributes that are assigned to an
object class. A filter can be set in order to query only for mandatory or prohibited attributes.
The parameters are:
• dictInfo Pointer to the dictionary context
• token Given object class alphanumeric token
• filter Filter specifications (see below)
• attrList Array of attribute tokens (return value)
The third parameter of this function specifies the filter conditions. The following values can
be used:
• EC_DICT_FULL_MANDATORY for attributes mandatory for the given class in any case,
• EC_DICT_COND_MANDATORY for attributes mandatory under certain circumstances,
• EC_DICT_PROHIBITED for attributes prohibited for the given object class,
• or any bit-wise combination of these values.
The memory for the returned list of attributes is allocated by this function and must be freed
by the application with the function EcFree. The function returns the number of attributes in
the returned list on success, and 0 on failure.
The following example shows the use of the function EcDictionaryGetObjectAttributes. All
attributes of the object class “DEPARE” are printed.
EcDictInfo *dictInfo;
int num;
EcAttributeToken *attrList;

// read the object and attribute dictionaries

if ((dictInfo = EcDictionaryReadModule(EC_MODULE_MAIN, NULL)) == NULL)
{ /* error handling */ }

200
 EC2007 ECDIS Kernel Programming Guide

num = EcDictionaryGetObjectAttributes(dictInfo, "DEPARE", 0,

&attrList);
printf("Attributes of class DEPARE:\n");
for (int i=0; i<num; i++)
{
printf("\t%s\n", attrList[i]);
}
if (num>0) EcFree(attrList);
// free dictionaries
EcDictionaryFree(dictInfo);

To find out whether it is allowed to assign a particular attribute to a given object class the
function EcDictionaryAttributeAllowed is used. The parameters are:
• dictInfo Pointer to the dictionary context
• classToken Given object class alphanumeric token
• attrToken Specified attribute alphanumeric token
There are also functions to get the allowed geometry of an object class,
EcDictionaryGetObjectGeometry, to get the default value for an attribute of an object class,
EcDictionaryGetDefaultAttributes, and to get the type of an object class,
EcDictionaryGetKindOfObject.
Similar functions are also available for accessing information about attributes. The function
EcDictionaryGetKindOfAttribute returns the type of the given attribute, which can be either a
feature, national feature, spatial or cartographic attribute.
The type of the attribute value can be retrieved with the function
EcDictionaryGetAttributeType.
This function returns the following defines for possible attribute types:

EC_ATTR_INT Integer value

EC_ATTR_ENUM Enumerated value (exactly one value from a list of possible attribute
values)
EC_ATTR_FLOAT Floating value
EC_ATTR_LIST List value (one or more values from a list of possible attribute
values)
EC_ATTR_ASCII String in a pre-defined format
EC_ATTR_STRING String in free format

Please note:
The coding of the strings must be in accordance with the lexical level, defined in the cell
header. For details please refer to the document EC2007_BackgroundInformation.

To check whether a value is allowed for an enumeration or list attribute the function
EcDictionaryEnumAllowedForAttribute can be used. The parameters are:

201
EC2007 ECDIS Kernel Programming Guide

• dictInfo Pointer to the dictionary context

• attrToken Specified attribute token
• enumValue Given enumeration value
This function returns EC_DICT_OK if the specified value is a valid enumeration value for the
given attribute. If the value is not allowed or the specified attribute is not found in the
dictionary the function returns EC_DICT_NOTFOUND. In case of an error, for instance if the
attribute value type is not enumeration or list, the function returns EC_DICT_ERROR.
More information about attributes, like maximum and minimum values, can be retrieved
with the functions EcDictionaryGetAttributeMaxValue and EcDictionaryGetAttributeMinValue.
The following example lists all enumeration values for the given attribute “CATLAM”
(Category of lateral mark):
EcDictInfo *dictInfo;
EcAttributeToken *attrTok = "CATLAM";
EcAttributeType attrType;
double maxValue;
char buf[256];

if ((dictInfo = EcDictionaryReadModule(EC_MODULE_MAIN, NULL)) == NULL)

{ /* error handling */ }

if(EcDictionaryGetAttributeType(dictInfo, attrTok, &attrType) !=

EC_DICT_OK)
{ /* error handling */ }

if(attrType != EC_ATTR_ENUM && attrType != EC_ATTR_LIST)

{ /* error handling */ }

if(EcDictionaryGetAttributeMaxValue(dictInfo, attrTok, &maxValue) !=

EC_DICT_OK)
{ /* error handling */ }

if(EcDictionaryTranslateAttributeToken(dictInfo, attrTok, buf,

sizeof(buf)) != EC_DICT_OK)
{ /* error handling */ }

printf("Attribute %s: %s\n", attrTok, buf);

for (int i=1; i<=(int)maxValue; i++)
{
if(EcDictionaryEnumAllowedForAttribute(dictInfo, attrTok, i) ==
EC_DICT_OK)
{
char val[256];
sprintf(val, "%s%d", attrTok, i);
EcDictionaryTranslateAttributeValue(dictInfo, val, buf,
sizeof(buf));
printf("\t[%2d] - %s\n", i, buf);
}
}
// free dictionaries

202
 EC2007 ECDIS Kernel Programming Guide

EcDictionaryFree(dictInfo);

Attribute values are stored in the data as ASCII strings. To convert them into a numeric value
the function EcDictionaryConvertAttribute can be used. The parameters are:
• dictInfo Pointer to the dictionary context
• attrCode Concatenation of attribute token and value
• result Pointer to the result (type see below)
This function converts the value of an attribute from string format into a numeric value. The
type of the result has to match the type of the attribute. The following types are requested:

Attribute type C type

EC_ATTR_INT int
EC_ATTR_ENUM int
EC_ATTR_FLOAT double
EC_ATTR_LIST int *
EC_ATTR_ASCII char *
EC_ATTR_STRING char *

For the types EC_ATTR_LIST, EC_ATTR_ASCII, and EC_ATTR_STRING the function allocates
memory for the result. This must be freed by using EcFree.

203
EC2007 ECDIS Kernel Programming Guide

11 Data Access
11.1 Cell File Access
The containers carrying data in the SevenCs SENC are called cells. Cells are implemented as
files. Each cell contains information about a specific geographic area. The coverage of a cell
specifies the areas inside the cell containing actual data. There is no need for completeness;
within a cell there can be sub-areas with no data. The extension of a cell is given by the
conjunction of all objects of this cell and cannot be set explicitly. Cell files usually have the
extension *.7CB.
The functions of the function group Cell Access of the set Ec27_Vector are used to access the
cell files. They are described in detail below.
As mentioned in document EC2007_BackgroundInformation the S-57 standard specifies a
transfer format for electronic navigational charts which is not suited for direct data access.
The SevenCs SENC format has been developed to ensure an efficient data access. S-57 ENCs
can be easily converted into the binary SENC format with the respective ECDIS Kernel
functions. All functions described here only access files in the binary SENC format.
Mainly two steps are necessary to access a cell file:
• mapping the cell and
• setting the appropriate access.
These two steps are implemented in one Kernel function, EcCellMap. This function takes the
following parameters:
• cellFileName Full name of the cell file including path and file extension
• accessmode Type of access (read, write or no access)
• timeout Timeout for setting the access
This function returns the cell ID if the cell was successfully mapped and the given access
mode could be set. If an error occurs the value EC_NOCELLID is returned. This cell ID of type
EcCellId is needed in many other ECDIS Kernel functions to access the cell’s data.
The potential values for the second parameter accessmode are:

EC_ACCESSREAD
EC_ACCESSWRITE
EC_ACCESSNOACCESS
If the cell ID is no longer needed in the application the cell must be unmapped with the
function EcCellUnmap. This function takes the cell ID as only parameter.
The access mode of a cell can be changed later in the application by means of the two
functions EcCellAccessSet and EcCellAccessRelease. In multithreaded applications it is possible
that several threads have read access to a particular cell. However, if one thread has write
access to a cell no other thread can have either write or read access to that cell. In these
multithreaded applications it is best to map the cell without access (EC_ACCESSNOACCESS).
Then set the appropriate access mode every time something is done with the cell, and
release the access mode directly after the operation. In order to give another thread the

204
 EC2007 ECDIS Kernel Programming Guide

chance to finish its operation, the EcCellAccessSet function should be called with a timeout
value. This is particularly necessary if at least one thread will access the cell for writing.
The function EcCellAccessSet sets the access mode for a given cell. The parameters are:
• cid Identifier of a mapped cell (as returned by the function EcCellMap)
• accessmode Type of access (read, write or no access)
• timeout Timeout for setting the access
This function returns True if the requested access mode was successfully set for the given
cell, and False otherwise.
To set the access mode of a given cell to no access the function EcCellAccessRelease can be
used. This function takes the cell ID as only parameter.
To find out what access mode is currently set for a particular cell the function EcCellAccessGet
can be used. This function also takes the cell ID as only parameter, and returns the current
cell access mode.

11.2 Cell Header Access

In the so-called cell header all meta information of the cell or chart are stored. For a detailed
list of parameters please refer to the document EC2007_BackgroundInformation.
Once the cell is mapped and the appropriate access has been set the information contained
in the cell can be read with the respective Kernel functions. To retrieve information stored in
the header of the cell the function EcCellGetHeaderInfo is used. The function takes the
following parameters:
• cid Identifier of a mapped cell (value is returned by the function EcCellMap)
• request Specifies the header information to be queried (see below)
• value Pointer to the returned value
• buffsize Size of value if the returned value is of type char*
The defines which can be specified for the parameter request are listed below:

Request Data type Description

EC_HDR_CONT INT32 Content of the cell
EC_HDR_INTU INT32 Intended usage of the cell
EC_HDR_ONAME char * Original S-57 Filename
EC_HDR_AGEN INT32 Agency code
EC_HDR_ICCD char[ 8] Individual Cell Code for the agency

EC_HDR_EDTN INT32 Chart edition number

EC_HDR_UPDN INT32 Serial number of last exchange set
EC_HDR_UADT char[12] Update Date

205
EC2007 ECDIS Kernel Programming Guide

EC_HDR_ISDT char[12] Issue Date

EC_HDR_STVR char[ 8] S57-Version String

EC_HDR_PRED char[ 8] Product Spec edition
EC_HDR_PSDN char * Product Spec description
EC_HDR_DSTR INT32 Topology

EC_HDR_AALL INT32 Attributes lexical level

EC_HDR_NALL INT32 National Attributes lexical level
EC_HDR_HDAT INT32 Horizontal datum
EC_HDR_VDAT INT32 Vertical datum
EC_HDR_SDAT INT32 Sounding datum
EC_HDR_CSCL INT32 Compilation scale
EC_HDR_DUNI INT32 Depth units
EC_HDR_HUNI INT32 Height units
EC_HDR_PUNI INT32 Units of Positional Accuracy
EC_HDR_COMF INT32 Coordinate Multiplication Factor
EC_HDR_SOMF INT32 Sounding Multiplication Factor

EC_HDR_LLLAT EcCoordinate South west latitude of cell coverage

EC_HDR_LLLON EcCoordinate South west longitude of cell coverage
EC_HDR_URLAT EcCoordinate North east latitude of cell coverage
EC_HDR_URLON EcCoordinate North east longitude of cell coverage

EC_HDR_NOBJS INT32 Number of objects in the cell

EC_HDR_DSID_COMT char * Comment of DSID Field

EC_HDR_DSPM_COMT char * Comment of DSPM Field

An example of how to use these functions is given in the example program readhead.

11.2.1 Cell Name

The header information also contains the original S-57 file name (EC_HDR_ONAME).
However, this may be different from the current file name of the cell in SENC binary format,

206
 EC2007 ECDIS Kernel Programming Guide

e.g. the S-57 file name has the extension .000 and the corresponding cell file name has the
extension .7CB. To retrieve the current file name of a specific cell, as it is stored in the file
system, the function EcCellGetNameById is used. This function takes the cell ID as only
parameter and returns a pointer to a static string containing the cell’s file name. If an error
occurs, the function returns NULL. The returned pointer will be valid until the next call to
EcCellGetNameById.

11.2.2 Cell Product

Besides ENCs there are many other chart products which are based on the S-57 standard. To
retrieve the chart product of an S-57 cell the S-57 PRSP and PRED field is used. In the SENC
files these two parameters are combined in the request type EC_HDR_PRED. The following
character strings are allowed.

Chart Product EC_HDR_PRED value

ENC 2.0 EN2.0
IENC IN1.02, IN2.0, IN2.1, IN2.2, IN2.3
PENC PE1.0
bENC BE1.0
AML 1.0 – 2.1 CL1.0, ES1.0, LB1.0, MF1.0, RA1.0, SB1.0
CL2.1, ES2.1, LB2.1, MF2.1, RA2.1, SB2.1
AML 3.0 AM3.0

11.3 Cell Data Access

The data stored in a cell consist of the header information described above and the actual
objects of a cell. These objects are composed of the three object components: feature
object, primitive, and node or edge. These components are stored in chained lists inside the
cell. The following sections describe the structures of these components and the functions
needed to access them.

11.3.1 Retrieving Cells

There are different functions to retrieve cells for further data access.
EcChartGetLoadedCellsOfView will return all cells which are currently assigned to the given
view.
EcCellLoadByArea and EcCellLoadByPolygon[Ext] and EcCellLoadBestByPrimitive do not retrieve
the cells from the view but from the catalogue list (see chapter 6.5.3).

207
EC2007 ECDIS Kernel Programming Guide

11.3.2 Retrieving Feature Objects

As described above the feature objects, as one object component, are stored in a chained
list inside the cell. This list can be directly accessed with the function EcFeatureGetFirst. This
function takes the cell identifier as only parameter and returns a handle to the first feature
object of the feature object list of the specified cell. Together with the function
EcFeatureGetNext all feature objects contained in a cell can be retrieved sequentially from
the chained list of feature objects. The function EcFeatureGetNext takes a handle to a feature
object as only parameter and returns the next feature object in the list of features.

11.3.3 Retrieving Primitives, Nodes, and Edges

Analogous to the component feature object, the components primitive and node or edge
can be directly retrieved from a cell. The functions EcPrimitiveGetFirst and EcPrimitiveGetNext
are used to access all primitives of a cell, the functions EcNodeGetFirst and EcNodeGetNext
are used for nodes, and the functions EcEdgeGetFirst and EcEdgeGetNext for edges.
When using these functions a macro called ECOK is helpful to check for the end of the object
component list. This macro returns True if the passed handle is valid and False if a faulty
handle is passed or the end of the list has been reached.
The following example shows how the statistics on the total amount of all object
components, feature objects, primitives, nodes, and edges of a cell can be implemented.
char *cellName = "7C5ABCDE.7CB";
EcCellId cellid;
EcFeature feature;
EcPrimitive primitive;
EcNode node;
EcEdge edge;
int numFeatures, numPrim, numNodes, numEdges;

// map cell with read access

if((cellid = EcCellMap(cellName, EC_ACCESSREAD, 0)) == EC_NOCELLID )
{ /* error handling */ }

numFeatures = numPrim = numNodes = numEdges = 0;

// get the first feature object

feature = EcFeatureGetFirst(cellid);
while (ECOK(feature))
{
numFeatures++;
// get the next feature object
feature = EcFeatureGetNext(feature);
}

// count the primitives of the cell

primitive = EcPrimitiveGetFirst(cellid);
while (ECOK(primitive))
{

208
 EC2007 ECDIS Kernel Programming Guide

numPrim++;
primitive = EcPrimitiveGetNext(primitive);
}

// count the nodes of the cell

node = EcNodeGetFirst(cellid);
while (ECOK(node))
{
numNodes++;
node = EcNodeGetNext(node);
}

// count the edges of the cell

edge = EcEdgeGetFirst(cellid);
while (ECOK(edge)
{
numEdges++;
edge = EcEdgeGetNext(edge);
}

EcCellUnmap(cellid);

11.3.4 Accessing Feature Objects

The component feature object has the following parameters which can be accessed by
means of different Kernel functions:
• class token
• group
• record ID
• object ID
• status
• attribute list
• relation to other feature objects
• relation to primitives

[Link] Class Token

The class token specifies the class the feature object belongs to. This parameter can be
retrieved with the function EcFeatureGetClass. This function takes the following parameters:
• feature Handle of the feature object (of type EcFeature)
• dictinfo Pointer to an object dictionary context as returned by the function
EcDictionaryReadExt
• buffer Character buffer for the class token
• buflen Length of buffer

209
EC2007 ECDIS Kernel Programming Guide

This function returns True on success and False otherwise.

To find out if a given feature object is of a particular class the function EcFeatureIsClass can
be used. The parameters are:
• feature Handle of the feature object
• dictinfo Pointer to an object dictionary context
• classname Class token to be checked
This function returns True if the specified class token matches the class of the feature object,
and False otherwise. This function has a better performance than retrieving the class name
with EcFeatureGetClass, and then comparing the strings.

[Link] Group
In S-57 each feature object belongs to a particular group. The possible group values are 1 for
skin of the earth objects, and 2 for all other objects. To retrieve the group value a given
feature object belongs to the function EcFeatureGetGroup is used. This function takes the
handle of the feature object as only parameter and returns the group value.

[Link] Identifiers
The parameters record ID and object ID are used to uniquely identify the feature object. The
record ID is mainly used for updating an S-57 cell in order to identify the modified objects of
the cell. The functions EcFeatureGetObjectId and EcFeatureGetRecId are used to retrieve these
identifiers of a given feature object.
To find a particular feature inside a cell when one of the identifiers is given the functions
EcQueryFeatureByObjectId and EcQueryFeatureByRecId can be used. These functions take the
handle of the starting feature object and the respective identifier (object ID or record ID) as
parameters, and return a handle of the corresponding feature object. The starting feature
object indicates at what point in the chained list of feature objects the search is started.
These functions perform a linear search on the list of feature objects with linear time
complexity.

[Link] Status
The status parameter is not part of the S-57 objects. This value is only evaluated by the
ECDIS Kernel functions. Possible values are:
• EC_OS_DELETABLE
• EC_OS_USERDEFINED
• EC_OS_SYSTEMDEFINED
This parameter is set when creating your own feature objects. To retrieve the status of a
feature object the function EcFeatureGetStatus is used. This function takes a handle of the
feature object as only parameter and returns the feature object’s status.

[Link] Attributes
All attribute tokens and their corresponding values are stored sequentially in so-called
attribute lists. A single attribute including its value can be retrieved one by one by means of
the function EcFeatureGetAttributes. The parameters are:
• feature Handle of the feature object

210
 EC2007 ECDIS Kernel Programming Guide

• dictinfo Pointer to an object dictionary context

• fi Pointer to EcFindInfo type for storing the iteration state
• first Flag that indicates first or subsequent calls
• attrbuf Character buffer for storing the attribute token and value
• buflen Length of attrbuf
The parameter first should be EC_FIRST when calling the function for the first time and
EC_NEXT in all subsequent calls.
The result of this function is a combination of attribute token and attribute value stored in
the parameter attrbuf. The functions EcDictionaryTranslateAttributeValue and
EcDictionaryConvertAttribute can be used to translate the attribute value into human-
readable text or convert it into a numeric value. The function returns True on success and
False if no more attributes exist for the given feature object.

Please note:
No attributes must be inserted into or removed from the feature object between the
calls of EcFeatureGetAttributes.

To retrieve the wide character attributes of a feature object the function

EcFeatureGetAttributesW can be used. Analogous to the function above this function retrieves
the attributes one by one. However, the attribute token and the attribute value are stored in
two different parameters. Wide character attributes are usually used for national object
names only.
An example for retrieving all attributes of a node is given later in this chapter. The procedure
is the same as retrieving attributes of a feature object.
To find out whether a given or known attribute is included in the attribute list of a feature
object the function EcFeatureQueryAttribute is used. The attribute is specified by its token,
and the combination of attribute token and attribute value is returned. The function takes
the following parameters:
• feature Handle of the feature object
• dictinfo Pointer to an object dictionary context
• attrtoken Given attribute token
• attrbuf Character buffer for storing the attribute token and value
• buflen Length of attrbuf
If this function returns False the specified attribute is either not contained in the attribute
list of the feature object, the attribute is not included in the dictionary or the attribute value
is a wide character string.
If the attribute value is a wide character string the function EcFeatureQueryAttributeW is
used. This function is analogous to the function EcFeatureQueryAttribute, except that it
returns the attribute value and not a combination of attribute token and value.
The next example shows how to query for attribute values according to their attribute type.
For integer and float values the function EcDictionaryConvertAttribute can be used to convert
the the value to perform a numeric comparison.
211
EC2007 ECDIS Kernel Programming Guide

char *cellName = "7C5ABCDE.7CB";

char attrBuf[256];
char attrValue[256];
EcCellId cellid;
EcDictInfo *dictInfo;
EcFeature feature;
EcAttributeType attrType;
double drval1;
int counter;

// read the object and attribute dictionaries

if ((dictInfo = EcDictionaryReadModule(EC_MODULE_MAIN, NULL)) == NULL)
{ /* error handling */ }

// map cell with read access

if((cellid = EcCellMap(cellName, EC_ACCESSREAD, 0)) == EC_NOCELLID )
{ /* error handling */ }

counter = 0;
// get the first feature object
feature = EcFeatureGetFirst(cellid);
while (ECOK(feature))
{
// is the feature object of class depth area?
if( EcFeatureIsClass(feature, dictInfo, "DEPARE"))
// get the attribute token and value for “DRVAL1”
if(EcFeatureQueryAttribute(feature, dictInfo, "DRVAL1",
attrBuf, sizeof(attrBuf)))
{
EcDictionaryConvertAttribute(dictInfo, attrBuf, &drval1));
if(drval1 == 10)
counter++;
}
// get the next feature object
feature = EcFeatureGetNext(feature);
}

// free dictionaries
EcDictionaryFree(dictInfo);

// unmap cell
EcCellUnmap(cellid);

The same result can be achieved with the high level function EcQuerySpotCell. This function
retrieves feature objects of a given cell filtered by the specified class and attributes. The
parameters are:
• cellid Identifier of a mapped cell
• dictinfo Pointer to an object dictionary context
• classname Given class token
• attrstr Given attribute tokens and values
212
 EC2007 ECDIS Kernel Programming Guide

• delimiter Delimiter used in attrstr

• fi Pointer to EcFindInfo type for storing the iteration state
• first Flag that indicates first or subsequent calls
• lat Latitude of object
• lon Longitude of object
This function returns a handle of a feature object. The returned object position (parameters
lat, long) is a representative position.

[Link] Relation to Feature Objects

A feature object may also have relations to other feature objects. Valid feature to feature
relations are master to slave and peer to peer relations. For example, a buoy is a feature
object that may have a master to slave relation to a top mark or light feature object. For the
peer to peer relation there are special collection objects of type association or aggregation,
which hold the common attributes and the relations to the feature objects belonging
together. For example, a traffic separation scheme system is an aggregation, and a feature
object of class synchronized lights is an association.

[Link] Retrieving Feature Objects Related to a Given Feature Object

To retrieve all feature objects related to a given feature object the function
EcFeatureGetAllFeatures is used. This function returns all related feature objects and their
relation type in a list of objects and relation types respectively. The parameters are:
• feature Handle of the feature object
• objList List of all related feature objects
• relist List of relation type (same index as objList)
The return value of this function is the number of related feature objects. If an error occurs
the return value is –1.

Please note:
This function allocates memory to the two lists objList and relList, which must be freed
by the application using the function EcFree.

If there are no related feature objects (return value 0), the parameters objList and relList are
undefined.
Each of the parameters objList and relList may also be NULL, in which case no memory is
allocated to the list. This also means that if both parameters are NULL the function only
returns the number of relations.

[Link] Retrieving Feature Objects Related to a Given Feature Object One by One
To retrieve the related feature objects of a given feature one by one the function
EcFeatureGetFeature can be used. The parameters are:
• feature Handle of the feature object
• fi Pointer to EcFindInfo type for storing the iteration state
• first Flag that indicates first or subsequent calls

213
EC2007 ECDIS Kernel Programming Guide

• relation Type of relation

The relation type returned may have the following values:
• EC_MASTER_OF or EC_SLAVE_OF,
• EC_BELONGS_TO or EC_HAS_A,
• EC_CONSISTS_OF or EC_IS_PART_OF,
• EC_HAS_MEMBER or EC_IS_MEMBER_OF,
• EC_IS_RELATED_TO

[Link] Relation to Primitives

The description of the SevenCs data model in chapter 6 The SevenCs Data Model shows that
an object not only consists of a feature object but also of a spatial object. The feature object
is the describing part which includes the main attributes and which is connected to the
spatial part through a link to a primitive.
Since this connection is mandatory for geographic objects it is always possible to retrieve
information about the primitives of an object by means of the feature object. The collection
objects mentioned above do not have a geographic position, therefore they are not linked to
any primitives. They are, however, always related to other feature objects.

11.3.4.10Retrieving all Primitives of a Given Feature Object

The function that retrieves all primitives of a given feature object is called
EcFeatureGetAllPrimitives. This function returns all primitives linked to the given feature
object and their minimum and maximum scale values in a list of primitives and two integer
lists respectively. The parameters are:
• feature Handle of the feature object
• primList List of all linked primitives
• sminList List of minimum scale values of primitives
• smaxList List of maximum scale values of primitives
The return value of this function is the number of linked primitives. If an error occurs the
return value is –1.

Please note:
This function allocates memory to the three lists primList, sminList, and smaxList, which
must be freed by the application using the function EcFree.

If there are no primitives linked to the feature object (return value 0), the parameters
primList, sminList, and relList are undefined.
Each of the parameters primList, sminList, and relList may also be NULL, in which case no
memory is allocated to the list. This also means that if all three parameters are NULL the
function only returns the number of relations.

11.3.4.11Retrieving Primitives of a Given Feature Object One by One

To retrieve the primitives related to the given feature object one by one the function
EcFeatureGetPrimitive can be used. The parameters are:

214
 EC2007 ECDIS Kernel Programming Guide

• feature Handle of the feature object

• fi Pointer to EcFindInfo type for storing the iteration state
• first Flag that indicates first or subsequent calls
• primtype Type of primitive
• scamin Minimum scale values of primitive
• scamax Maximum scale values of primitive
The primitive type returned may have the following values:
• EC_P_PRIM for point primitives
• EC_S_PRIM for sounding primitives
• EC_L_PRIM for line primitives
• EC_A_PRIM for area primitives
The return value of this function is a handle of the primitive on success, and an empty
handle if no more primitives exist or an error has occurred.

Please note:
The S-57 data model (see document EC2007_BackgroundInformation) does not include the
primitive layer. During the conversion of S-57 data into the SevenCs SENC format one
primitive is added for each geographic S-57 object. This indicates that all S-57 objects
have exactly one primitive and that only user-defined objects may have more than one
primitive.

In the following example all primitives are retrieved one by one from each feature object of
a given cell. The class name of each feature object and the types of its related primitives are
printed.
For example, the past track object known in the ECDIS Kernel has a line primitive for the
track itself and a cluster primitive (EC_S_PRIM) for the time tags on the track.
char *cellName = "7C5ABCDE.7CB";
EcCellId cellid;
EcDictInfo *dictInfo;
EcFindInfo fi;
EcFeature feature;
EcPrimitive primitive;
EcPrimitiveType primType;
INT32 scamin, scamax;
char className[42];

// read the object and attribute dictionaries

if ((dictInfo = EcDictionaryReadModule(EC_MODULE_MAIN, NULL)) == NULL)
{ /* error handling */ }

// map cell with read access

if((cellid = EcCellMap(cellName, EC_ACCESSREAD, 0)) == EC_NOCELLID )
{ /* error handling */ }

215
EC2007 ECDIS Kernel Programming Guide

// get the first feature object

feature = EcFeatureGetFirst(cellid);
while (ECOK(feature))
{
// get the class name of the feature object
if(EcFeatureGetClass(feature, dictInfo, className,
sizeof(className)))
fprintf(stdout, "feature object of class %s has:\n", className);
// get the first primitive of the feature object
primitive=EcFeatureGetPrimitive(feature, &fi, EC_FIRST,
&primType, &scamin,&scamax);
while(ECOK(primitive))
{
fprintf(stdout," primitive of type ");
switch(primtype)
{
case EC_A_PRIM:
fprintf(stdout,"area, ");
break;
case EC_L_PRIM:
fprintf(stdout,"line, ");
break;
case EC_P_PRIM:
fprintf(stdout,"point, ");
break;
case EC_S_PRIM:
fprintf(stdout,"sounding, ");
break;
}// switch
fprintf(stdout, "min scale: %d, max scale: %d\n", scamin, scamax);
// get next primitive of the feature object
primitive = EcFeatureGetPrimitive(feature, &fi, EC_NEXT,
&primType, &scamin, &scamax);
}// while
// get the next feature object
feature = EcFeatureGetNext(feature);
}// while

// free dictionaries
EcDictionaryFree(dictInfo);
// unmap cell
EcCellUnmap(cellid);

11.3.5 Accessing Primitives

A geographic feature object is always linked to at least one primitive which holds
information about the geometry of the object. The parameters of a primitive can also be
accessed using EC2007 ECDIS Kernel functions.
• record id

216
 EC2007 ECDIS Kernel Programming Guide

• status
• type
• relation to feature objects
• list of segments (nodes or edges)

[Link] Identifier and Status

The parameter record ID is analogous to the identifiers of the feature objects, and is used to
uniquely identify the primitives of a cell. The function EcPrimitiveGetRecId retrieves the value
of this parameter for a given primitive. The chained list of primitives in a cell can also be
queried for a primitive with a specific record ID using the function EcQueryPrimitiveByRecId.
The status of a primitive is also analogous to the status of a feature object and can be
retrieved by means of the function EcPrimitiveGetStatus.

Please note:
For S-57 objects the record ID of the primitive is logically linked to the record ID of the
corresponding feature object for line and area primitives, or to the record ID of the
corresponding nodes for point or cluster primitives.

[Link] Type
The type of a primitive holds the information about the geometry of an object.
The following values are possible for this parameter:
• EC_P_PRIM for point primitives
• EC_S_PRIM for cluster primitives (mainly used for soundings)
• EC_L_PRIM for line primitives
• EC_A_PRIM for area primitives
The function EcPrimitiveGetType is used to retrieve the type of a given primitive. This function
takes a handle of the primitive as only parameter, and returns the primitive type. If an error
occurs the return value will be -1.

[Link] Relation to Feature Objects

As mentioned above a primitive, as part of an object, is linked to at least one feature object.
If more than one object is located at the same geographic position they can be linked to the
same primitive. For example a buoy object and its top mark and light objects will all be
linked to the same primitive.

[Link] Retrieving All Feature Objects Linked to a Primitive

To retrieve all feature objects linked to a given primitive the function
EcPrimitiveGetAllFeatures is used. All feature objects related to the specified primitive are
stored in a list of features, and the number of features is returned. The parameters of this
function are:
• primitive Handle of the primitive
• fList List of all related feature objects

217
EC2007 ECDIS Kernel Programming Guide

Please note:
This function allocates memory to the list of feature objects fList which must be freed by
the application using the function EcFree.

The parameter fList may also be NULL, in which case no memory is allocated for the list of
features, and only the number of relations is returned.

[Link] Retrieving Feature Objects Linked to a Primitive One by One

To retrieve the feature objects linked to a given primitive one by one the function
EcPrimitiveGetFeature is used. This function is applied in the same way as the functions
EcFeatureGetPrimitive and EcFeatureGetFeature. The parameters are:
• primitive Handle of the primitive
• fi Pointer to EcFindInfo type for storing the iteration state
• first Flag that indicates first or subsequent calls
The return value of this function is a handle of the related feature object. This handle is
empty if no more related feature objects exist or an error has occurred.

[Link] List of Segments

The third component of a complete object is the segment. Each primitive, as part of an
object, is linked to at least one segment. Depending on the primitive type these segments
are either nodes or edges. Point primitives are linked to exactly one node, cluster primitives,
e.g. soundings, are linked to more than one node, and line and area primitives are linked to
one or more edges.

[Link] Retrieving all Nodes or Edges Related to a Primitive

To retrieve all nodes or edges related to a primitive the functions EcPrimitiveGetAllNodes or
EcPrimitiveGetAllEdges are used respectively.
The function EcPrimitiveGetAllNodes retrieves all nodes linked to a given point or cluster
primitive, and stores them in a list of nodes. The return value is the number of nodes in this
list of related nodes. The parameters of this function are:
• primitive Handle of the primitive
• nodeList List of all related feature objects

Please note:
This function allocates memory to the list of nodes nodeList which must be freed by the
application using the function EcFree.

The parameter nodeList may also be NULL, in which case no memory is allocated to the list
and only the number of relations is returned. If no node is related to the given primitive
(return value 0) the parameter nodeList is undefined.
The function EcPrimitiveGetAllEdges retrieves all edges linked to a given line or area primitive
and stores the edges, their orientation and usage in three lists. The parameters are:
• primitive Handle of the primitive

218
 EC2007 ECDIS Kernel Programming Guide

• edgeList List of all linked edges

• orntList List of orientation used for edges in edgeList (same index)
• usagList List of usage of edges in edgeList (same index)
The return value of this function is the number of linked edges. If an error has occurred the
return value will be -1.

Please note:
This function allocates memory to the three lists edgeList, orntList, and usagList which
must be freed by the application using the function EcFree.

In case there are no edges linked to the primitive (return value 0), the parameters edgeList,
orntList, and usagList are undefined.
Each of these parameters may also be NULL, in which case no memory is allocated to the list.
This also means that if all three are NULL the function only returns the number of relations.
The values for the orientation of an edge can be either EC_FORWARD or EC_REVERSE. The
values for the usage of an edge can be as follows:
• EC_USAGE_EXT for outer edges of an area
• EC_USAGE_IN0 for first inner edges of an area (islands)
• EC_USAGE_IN1 for all other inner edges of an area
• EC_USAGE_CBD for outer edges of an area that are part of a cell boundary

[Link] Retrieving Nodes or Edges Related to a Primitive One by One

To retrieve the nodes or edges related to a given primitive one by one the functions
EcPrimitiveGetNode and EcPrimitiveGetEdge can be used respectively. These functions are
applied in the same way as the functions EcFeatureGetPrimitive, EcFeatureGetFeature, and
EcPrimitiveGetFeature.
The parameters for the function EcPrimitiveGetNode are:
• primitive Handle of the primitive
• fi Pointer to EcFindInfo type for storing the iteration state
• first Flag that indicates first or subsequent calls

The parameters of the function EcPrimitiveGetEdge are:

• primitive Handle of the primitive
• fi Pointer to EcFindInfo type for storing the iteration state
• first Flag that indicates first or subsequent calls
• ornt Orientation used for the edge
• usage Usage of the edge
The return value of these functions is a handle of the related node or edge. This handle will
be empty if no more related nodes or edges exist or an error has occurred.

219
EC2007 ECDIS Kernel Programming Guide

In the following example all primitives of a given cell are retrieved from the chained list of
primitives, and depending on the primitive type the number of nodes or edges is printed for
each primitive.
char *cellName = "7C5ABCDE.7CB";
EcCellId cellid;
EcPrimitive primitive;
EcPrimitiveType primType;
int numNodes, numEdges;

// map cell with read access

if((cellid = EcCellMap(cellName, EC_ACCESSREAD, 0)) == EC_NOCELLID )
{ /* error handling */ }

// get the first primitive of the cell

primitive = EcPrimitiveGetFirst(cellid);
while (ECOK(primitive))
{
// get the primitive type
primType = EcPrimitiveGetType(primitive);
if((primType == EC_P_PRIM)||(primType == EC_S_PRIM))
{
// get number of nodes linked to primitive
numNodes = EcPrimitiveGetAllNodes(primitive, NULL);
if(primType == EC_S_PRIM)
fprintf(stdout, "primitive of type sounding has ");
else
fprintf(stdout, "primitive of type point has ");
fprintf(stdout, "%d nodes.", numNodes);
}//if
if((primType == EC_L_PRIM)||(primType == EC_A_PRIM))
{
// get number of edges linked to primitive
numEdges = EcPrimitiveGetAllEdges(primitive, NULL, NULL, NULL);
if(primType == EC_A_PRIM)
fprintf(stdout, "primitive of type area has ");
else
fprintf(stdout, "primitive of type line has ");
fprintf(stdout, "%d edges.", numEdges);
}//if
// get next primitive of the cell
primitive = EcPrimitiveGetNext(primitive);
}// while
// unmap cell
EcCellUnmap(cellid);

220
 EC2007 ECDIS Kernel Programming Guide

11.3.6 Accessing Nodes

The primitives of type point and cluster contain nodes, which hold the geographic
information about the object. The parameters of a node can be accessed with Kernel
functions.
• record ID
• status
• type
• position
• depth
• dimension
• attribute list
• relation to primitives

[Link] Identifier and Status

The parameters record ID is analogous to the identifiers of the feature objects and primitives
and is used to identify the nodes of a cell. The function EcNodeGetRecId retrieves the values
of this parameter for a given node.
The chained list of nodes in a cell can also be queried for a node with a specific record ID
using the function EcQueryNodeByRecId.
The status of a node is also analogous to the status of a feature object and a primitive, and
can be retrieved by means of the function EcNodeGetStatus.

[Link] Type
The type of a node can be either EC_ISOLATED or EC_BOUNDING. A bounding node is
always related to an edge and describes its first or last vertex. These bounding nodes are
usually not referenced by any primitives unless an additional object, e.g. a buoy marking an
anchorage area, is located at that position.
The isolated nodes are always related to at least one point or cluster primitive.
The function EcNodeGetType is used to retrieve the type of a given node. This function takes
a handle of the node as only parameter, and returns the node type. If an error has occurred
the return value will be -1.

[Link] Position, Dimension, and Depth

The geographic position of a node is given in latitude and longitude. The dimension of a
node is either 2 or 3, and the third dimension is the depth of a node.

Please note:
Only isolated nodes may be three-dimensional, i.e. have a depth value, whereas
bounding nodes are always two-dimensional.

To retrieve the position, dimension, and possible depth value of a node the function
EcNodeGetPosition is used. This function takes the following parameters:

221
EC2007 ECDIS Kernel Programming Guide

• node handle of the node

• lat Latitude of position in decimal degrees
• lon Longitude of position in decimal degrees
• depth Value of third dimension in meters (undefined if ndim = 2)
• ndim Dimension of node (2 or 3)
This function returns True on success and False otherwise.

[Link] Attribute List

The attribute list of each node contains all attribute tokens and their corresponding values.
These attributes can be retrieved one by one by means of the function EcNodeGetAttributes.
The parameters are:
• node Handle of the node
• dictinfo Pointer to an object dictionary context
• fi Pointer to EcFindInfo type for storing the iteration state
• first Flag that indicates first or subsequent calls
• attrbuf Character buffer for storing the attribute token and value
• buflen Length of attrbuf
The result of this function is a combination of attribute token and attribute value stored in
the parameter attrbuf.
The functions EcDictionaryTranslateAttributeValue and EcDictionaryConvertAttribute can be
used to translate the attribute value into human-readable text or convert it into a numeric
value.
The function returns True on success and False if no more attributes exist for the given node.

Please note:
No attributes may be inserted into or removed from the node between the calls of
EcNodeGetAttributes.

In S-57 there are currently only two attributes that are available for spatial objects (nodes
and edges): positional accuracy (POSACC), and quality of position (QUALPOS).
In the following example for all nodes of a given cell their type, position, depth (if existing),
and all their attributes are printed.
char *cellName = "7C5ABCDE.7CB";
EcCellId cellid;
EcDictInfo *dictInfo;
EcFindInfo fi;
EcNode node;
EcNodeType nodeType;
EcCoordinates lat, lon;
int ndim;
double depth;
char attrbuf[256], buffer[256];

222
 EC2007 ECDIS Kernel Programming Guide

Bool result;
// read the object and attribute dictionaries
if ((dictInfo = EcDictionaryReadModule(EC_MODULE_MAIN, NULL)) == NULL)
{ /* error handling */ }

// map cell with read access

if((cellid = EcCellMap(cellName, EC_ACCESSREAD, 0)) == EC_NOCELLID )
{ /* error handling */ }

// get the first node of the cell

node = EcNodeGetFirst(cellid);
while (ECOK(node))
{
// get the node type
nodeType = EcNodeGetType(node);
if(nodeType == EC_ISOLATED_NODE)
fprintf(stdout, "Isolated node at position: ");
if(nodeType == EC_BOUNDING_NODE)
fprintf(stdout, "Bounding node at position: ");
// get the coordinates of the node
if(EcNodeGetPosition(node, &lat, &lon, &depth, &ndim))
{
fprintf(stdout,"%f, %f\n", lat, lon);
if(ndim == 3) fprintf(stdout, " depth: %f\n", depth);
}
// get the first attribute of the node
result = EcNodeGetAttributes(node, dictInfo, &fi, EC_FIRST,
attrbuf, sizeof(attrbuf));
fprintf(stdout," Attributes:\n");
while(result)
{
// translate the attribute token and value into human-readable text
EcDictionaryTranslateAttributeToken(dictInfo, attrbuf,
buffer, sizeof(buffer));
fprintf(stdout, " %s ", buffer);
EcDictionaryTranslateAttributeValue(dictInfo, attrbuf,
buffer, sizeof(buffer));
fprintf(stdout, "%s\n", buffer);
// get next attribute of the node
result = EcNodeGetAttributes(node, dictInfo, &fi, EC_NEXT,
attrbuf,sizeof(attrbuf));
}// while
// get the next node of the cell
node = EcNodeGetNext(node);
}// while

// free dictionaries
EcDictionaryFree(dictInfo);
// unmap cell
EcCellUnmap(cellid);

223
EC2007 ECDIS Kernel Programming Guide

To find out whether a given attribute is included in the attribute list of the node the function
EcNodeQueryAttribute is used. The attribute is specified by its token, and the combination of
attribute token and attribute value is returned.
The function takes the following parameters:
• node Handle of the node
• dictinfo Pointer to an object dictionary context
• attrtoken Given attribute token
• attrbuf Character buffer for storing the attribute token and value
• buflen Length of attrbuf
If this function returns False the specified attribute is either not contained in the attribute
list of the node or the attribute is not included in the dictionary.

[Link] Relation to Primitives

As mentioned above each isolated node is linked to at least one primitive of the type point
or cluster, and a bounding node may be linked to a point primitive.
To retrieve all primitives of a given node the function EcNodeGetAllPrimitives is used. This
function returns all primitives linked to the given node in a list of primitives. The parameters
are:
• node Handle of the node
• primList List of all linked primitives
The return value of this function is the number of linked primitives. If an error has occurred
the return value will be -1.

Please note:
This function allocates memory to the list primList, which must be freed by the
application using the function EcFree.

In case there are no primitives linked to the node (return value 0) the parameter primList is
undefined. The parameter primList may also be NULL in which case no memory is allocated
to the list, and the function only returns the number of relations.

Retrieving Primitives of a Given Node One by One

To retrieve the primitives related to the given node one by one the function
EcNodeGetPrimitive can be used. The parameters are:
• node Handle of the node
• fi Pointer to EcFindInfo type for storing the iteration state
• first Flag that indicates first or subsequent calls
This function returns a handle of the related primitive, which can be of type EC_P_PRIM or
EC_S_PRIM. An empty handle is returned if no more related primitives exist or an error
occurred.

224
 EC2007 ECDIS Kernel Programming Guide

11.3.7 Accessing Edges

The primitives of type line and area contain edges which hold the geographic information
about the object. The parameters of an edge can be accessed with EC2007 ECDIS Kernel
functions.
• record ID
• status
• type
• dimension
• number of vertices
• vertex list
• attribute list
• relation to primitives
• relation to nodes (bounding nodes)

[Link] Identifier and Status

The parameter record ID is analogous to the identifiers of the feature objects, primitives,
and nodes. It is used to identify the edges of a cell. The function EcEdgeGetRecId retrieves the
value of this parameter for a given edge. The chained list of edges in a cell can also be
queried for an edge with a specific record ID using the function EcQueryEdgeByRecId.
The status of an edge is also analogous to the status of a feature object, primitive, and node.
It can be retrieved by means of the function EcEdgeGetStatus.

[Link] Vertex List, Number of Vertices and Dimension

The actual coordinates of each vertex of an edge are stored in an array. This list of vertices
can be retrieved with the function EcEdgeGetPosition. This function returns the vertex list of a
given edge and the number of entries in that list. The parameters are:
• edge Handle of the edge
• coor Array of vertices
The parameter coor contains repeating coordinate n-tupels where n is the dimension of
each vertex. The first two entries of each n-tupel are reserved for the latitude and longitude
in decimal degrees, and all other entries have to be interpreted as 32 bit integer values.

Please note:
The function allocates memory to the list of vertices which must be freed by the
application with the function EcFree.

The return value of the function EcEdgeGetPosition is the number of vertices of the given
edge. This value can also be retrieved by means of the function EcEdgeGetNumberOfVertices.
This function takes a handle of the edge as only parameter and returns the number of
vertices in the edge’s vertex list.
To extract the coordinates of each vertex of the array of vertices returned by the function
EcEdgeGetPosition the number of vertices in that array and the dimension of each vertex are

225
EC2007 ECDIS Kernel Programming Guide

needed. To retrieve the dimension of the vertices the function EcEdgeGetDimension is used.
This function also takes a handle of the edge as only parameter and returns the dimension of
the vertices.
In the following example the coordinates (latitude and longitude) of all vertices of each edge
of a given cell are printed.
char *cellName = "7C5ABCDE.7CB";
EcCellId cellid;
EcEdge edge;
EcCoordinates *vertexList, lat, lon;
int numVertices, dim;

// map cell with read access

if((cellid = EcCellMap(cellName, EC_ACCESSREAD, 0)) == EC_NOCELLID )
{ /* error handling */ }

// get the first edge of the cell

edge = EcEdgeGetFirst(cellid);
while (ECOK(edge))
{
// get the vertices of the edge
numVertices = EcEdgeGetPosition(edge, &vertexList);
// get the dimension of the vertices
dim = EcEdgeGetDimension(edge);
// get the coordinates of each vertex
for(int i=0; i<numVertices; i++)
{
lat = vertexList[i*dim];
lon = vertexList[i*dim+1];
fprintf(stdout,"%3d Lat: %f Long: %f\n", i+1, lat, lon);
}
// free the memory of the vertex list
if(numVertices>0)
EcFree(vertexList);
// get the next edge of the cell
edge = EcEdgeGetNext(edge);
}// while

// unmap cell
EcCellUnmap(cellid);

It is also possible to retrieve the coordinates of a single vertex of the list of vertices of a given
edge. The function EcEdgeGetVertexPosition returns the coordinates of the specified vertex of
an edge. The parameters are:
• edge Handle of the edge
• index Index of vertex
• coor Array of coordinates
The vertex is specified by its index in the list of vertices of the given edge with 0 referencing
the first vertex. The length of the array coor depends on the dimension of the vertices.

226
 EC2007 ECDIS Kernel Programming Guide

Please note:
This function allocates memory to the array coor which must be freed by the application
using the function EcFree.

[Link] Attribute List

Analogous to the nodes an edge can also have an attribute list containing all attribute tokens
and their corresponding values. These attributes can be retrieved one by one by means of
the function EcEdgeGetAttributes. This function is used in the same way as the function
EcNodeGetAttributes described above. In addition there is a function available to check
whether a particular attribute is included in the attribute list of a given edge. The function
EcEdgeQueryAttribute for edges is analogous to the function EcNodeQueryAttribute for nodes.

[Link] Relation to Primitives

Each edge is linked to at least one primitive of the type line or area. To retrieve all primitives
of a given edge the function EcEdgeGetAllPrimitives is used. This function returns all
primitives linked to the given edge in a list of primitives. The parameters are:
• edge Handle of the edge
• primList List of all linked primitives
The return value of this function is the number of linked primitives. If an error occurs the
return value is -1.

Please note:
This function allocates memory to the list primList which must be freed by the
application using the function EcFree.

In case there are no primitives linked to the edge (return value 0), the parameter primList is
undefined. The parameter primList may also be NULL, in which case no memory is allocated
to the list, and the function only returns the number of relations.
To retrieve the primitives related to the given edge one by one the function
EcEdgeGetPrimitive can be used. The parameters are:
• edge Handle of the edge
• fi Pointer to EcFindInfo type for storing the iteration state
• first Flag that indicates first or subsequent calls
This function returns a handle of the related primitive which can be of type EC_L_PRIM or
EC_A_PRIM. An empty handle is returned if no more related primitives exist or an error has
occurred.

[Link] Relation to Bounding Node

In S-57 each edge has two bounding nodes which form the first and the last vertex of the
edge. In the SevenCs SENC format all vertices are contained in the vertex list, and the
bounding nodes are related to the edge. In the SENC format it is also not mandatory for an
edge to have two bounding nodes.

227
EC2007 ECDIS Kernel Programming Guide

If a bounding node is modified the vertex entry of the corresponding edge is modified
accordingly and vice versa. If an edge is related to bounding nodes this relation will be
deleted when the position of the edge is moved using EcEdgeSetPosition.
To retrieve the bounding nodes of an edge the function EcEdgeGetBoundingNode is used. The
parameters are:
• edge Handle of the edge
• ori Specifying first or last node
Possible values of the parameter ori are EC_FORWARD specifying the first bounding node,
and EC_REVERSE specifying the last bounding node. The return value of this function is a
handle to the node. If no bounding node exists for the given edge or an error has occurred
the returned handle will be empty.

11.4 Creating a Cell

There are various cases when creating a new cell is necessary. To create such new cell the
function EcCellCreate is used. This function creates a new cell of the binary SENC format and
sets default header information. The parameters are:
• name Name of the cell file to be created (including extension)
• minsize Initial size of the cell in bytes
The parameter name specifies the file name of the new cell, with the extension .7CB for the
SevenCs SENC format. The second parameter minsize indicates the initial file size of the cell
in bytes. This value does not restrict the size of the cell. As more data are added to the cell
the size of the cell will grow accordingly. This function returns True on success, and False
otherwise.
The following values are set in the cell header as defaults:

Intended usage of the cell (EC_HDR_INTU) EC_GENERAL

Chart edition number (EC_HDR_EDTN) 1
Serial number of last update (EC_HDR_UPDN) 0
Update Application Date (EC_HDR_UADT) current date
Issue Date (EC_HDR_ISDT) current date
Agency Code (EC_HDR_AGEN) 65534 (unknown)
S57-Version String (EC_HDR_STVR) "03.1"
Product Spec Edition (EC_HDR_PRED) "2.0"
Topology/Data Structure (EC_HDR_DSTR) 2 (Chain node)
Attributes lexical level (EC_HDR_AALL) 1
National attributes lexical level (EC_HDR_NALL) 1
Horizontal geodetic datum (EC_HDR_HDAT) 2 (WGS84),

228
 EC2007 ECDIS Kernel Programming Guide

Vertical datum (EC_HDR_VDAT) 3 (mean sea level)

Sounding datum (EC_HDR_SDAT) 1 (mean low water spring)
Compilation scale (EC_HDR_CSCL) 1
Units of depth measurement (EC_HDR_DUNI) 1 (meter)
Units of heights measurement (EC_HDR_HUNI) 1 (meter)
Units of positional accuracy (EC_HDR_PUNI) 1 (meter)
Coordinate Multiplication Factor (EC_HDR_COMF) 10000000
Sounding Multiplication Factor (EC_HDR_SOMF) 10

11.4.1 Setting Cell Header Values

To change the default values or set any of the header values the function EcCellSetHeaderInfo
can be used. In any case the new cell must first be mapped with write access.

11.4.2 Deleting Cells

Just as you can create a new cell there is also a function for deleting a cell. This function is
called EcCellDelete and it removes the cell specified by its name from the file system. The
only parameter is the file name including path and extension. Before deleting a cell from the
file system it should be unmapped by means of the function EcCellUnmap.

11.4.3 Deleting Cell Content

If only the content of the cell is to be removed, the function EcCellClear is used. This function
removes all data contained in the specified cell, and sets the header information to default
values. The only parameter is the cell identifier of a mapped cell. After calling this function
the given cell will be completely empty and contain no objects.

11.4.4 Reorganizing the Cell, Reducing its Size

When performing many operations on a cell, like adding and removing objects, the cell will
automatically enlarge its size and space no longer used inside the cell will be collected as
garbage.
This garbage is collected by an internal memory management and is then reused by the
ECDIS Kernel functions. To eliminate any remaining garbage blocks that could not be reused
the function EcCellForceCleanup is utilized. This function reorganizes the entire cell, and
reduces its size to a minimum. Any unused memory blocks will be freed. The function
EcCellForceCleanup takes the following parameters:
• cid Identifier of a mapped cell
• errlog Open file handle for error messages (not used, only for backward

229
EC2007 ECDIS Kernel Programming Guide

compatibility)
• bCompress Force space-efficient storage

11.4.5 Specifying the Storage Type

In the SevenCs ECDIS Kernel the vertices are stored in arrays instead of linked lists to enable
a more efficient use of memory space in the cell. The transformation from the storage type
array to list for a simple edge will be done implicit by all functions editing the vertex list of an
edge. With the function EcCellForceCleanup the storage type can be explicitly specified. If the
parameter bCompress is set to True the storage type array will be used, if bCompress is set
to False the storage type linked list will be used. The storage type list is not as space efficient
but faster for write operations on the vertex list in the cell.

Please note:
All handles to object components of this cell will become invalid after reorganizing the
cell with the function EcCellForceCleanup. That is why this function should not be called
between any data operations on the cell.

11.4.6 Removing Orphaned Object Components

The SevenCs data model described in the document EC2007_BackgroundInformation shows
that objects contained in a cell consist of different object components which are linked
together. An object therefore contains a feature object and a primitive, which references
one or more nodes or edges. An object component is ‘orphaned’ when no other object
component is related to it, e.g. a feature object that has no primitive or a primitive without
any nodes or edges. To remove these orphaned object components and fragments from the
data structure without reorganizing the
cell the function EcCellRemoveOrphans can be used. This function takes the following
parameters:
• cid Identifier of the cell
• errlog Open file handle for error messages
• errorcount Number of orphaned object components found
If the file handle errlog is not NULL diagnostics are written to it. When calling this function
the handles to object components not yet deleted are still valid, and further data operations
can be performed on the cell. A feature object is orphaned if it is neither linked to any
primitives nor related to other feature objects.
A primitive is orphaned if it is not linked to any feature objects or any segments.
A node is orphaned if it is neither linked to any non-orphaned point or cluster primitives nor
to any edges (in case of a bounding node).
An edge is orphaned if it is not linked to any non-orphaned line or area primitives.

230
 EC2007 ECDIS Kernel Programming Guide

11.4.7 Checking Cells for Errors in Data Structure

To check whether a cell has no errors in its data structure the function EcCellCheck can be
used. The parameters are:
• cid Identifier of the cell.
• errlog Open file handle for error messages
This function checks the data structure of a cell by searching for distorted object
components and dangling pointers. The parameter errlog exists only for backward
compatibility. If this function returns False the cell is damaged. It can no longer be used, and
has to be rejected. This test is also done internally during cell mapping, thus a cell with
structural errors cannot be mapped.
Applications may call EcCellCheck after a large number of complex cell manipulations, like
object create or delete operations.

11.5 Creating and Modifying Objects

11.5.1 Creating Objects

It is possible to create your own objects in a given cell.

Please note:
When creating a new object in a particular cell, or deleting or modifying objects in a cell,
this cell must be mapped with write access.

To create a complete object as feature object at least one primitive, and at least one node or
edge must be created and then linked together.
The function to create your own feature object is called EcFeatureCreate.
The following parameters are set when creating a new feature:
• cellid Identifier of a mapped cell
• dictinfo Pointer to an object dictionary context
• classname Object class token
• ftype Type of feature object (should be EC_SIMPLE_FOBJ)
• status Status of feature object
• attrstr Attribute tokens and values
• delimiter Delimiter used in attrstr
This function returns a handle of the created feature object which can be checked for errors
with ECOK.
The function EcPrimitiveCreate is used to create your own primitive.
The following parameters are set:
• cellid Identifier of a mapped cell

231
EC2007 ECDIS Kernel Programming Guide

• ptype Type of primitive (can be EC_P_PRIM, EC_S_PRIM, EC_L_PRIM or

EC_A_PRIM)
This function returns a handle of the newly created primitive. The primitive type, which
determines the geometry of an object, is the only parameter that must be set when creating
a new primitive. All other parameters of the primitive can be set with separate ECDIS Kernel
functions.
Now that a new feature object and a primitive exist the relation between these two
components must be created. To link a primitive to a feature object the function
EcPrimitiveLinkToFeature is used. This function takes the following parameters:
• feature Handle of the feature object
• primitive Handle of the primitive
• scamin Minimum display scale for primitive
• scamax Maximum display scale for primitive
This function returns True on success and False otherwise.
For a complete object at least one spatial component node or edge is still required.
The functions EcNodeCreate and EcEdgeCreate are used to create a new node or edge
respectively. The function EcNodeCreate takes the following parameters:
• cellid Identifier of a mapped cell
• lat Latitude of position in decimal degrees
• lon Longitude of position in decimal degrees
• depth Value of third dimension in meters (not used if ndim = 2)
• ndim Dimension of node (2 or 3)
This function returns the handle of the newly created node.
To prevent an isolated node from becoming orphaned it must be linked to a primitive of the
type point or cluster. The function EcNodeLinkToPrimitive is used to create the relation
between a node and a primitive. The parameters are:
• primitive Handle of the primitive
• node Handle of the node
This function returns True on success and False otherwise.
The function EcEdgeCreate takes the following parameters:
• cellid Identifier of a mapped cell
• coorList Array of coordinates of the vertices
• nocoor Number of vertices (coordinate n-tuples)
• dim Dimension of vertices (at least 2)
• type Type of edge (can be EC_TYPE_STD or EC_TYPE_SBK)
This function returns a handle of the newly created edge.

232
 EC2007 ECDIS Kernel Programming Guide

The edge type EC_TYPE_STD is used for normal edges. The edge type EC_TYPE_SBK is used
for so-called source break edges. Objects which are linked to such an edge are displayed in a
faint grey color.
To prevent an edge from becoming orphaned it must be linked to a primitive of the type line
or area. If a primitive of type line or area includes a list of related edges that contains more
than one edge the order in which these edges are stored in the list is important. This is why
there are two functions to create the relation between an edge and a primitive.
The function EcEdgeAppendToPrimitiveExt is used in case the edge shall be added to the end
of the segment list of a given primitive. The parameters are:
• primitive Handle of the primitive
• edge Handle of the edge
• usage Usage of the edge
• ornt Orientation used for the edge
• mask Visualization of the edge (can be EC_MASK_SHOW or EC_MASK_HIDE)
This function returns True on success and False otherwise.

Please note:
If you set the parameter mask to EC_MASK_HIDE the given edge will not be drawn for all
feature objects linked to the given primitive.

The function EcEdgeInsertToPrimitiveExt is used in case the edge shall be inserted at a

specified position into the segment list of a given primitive. The parameters are:
• primitive Handle of the primitive
• where Index of segment list where the edge is to be inserted (0 indicates first
position)
• edge Handle of the edge
• usage Usage of the edge
• ornt Orientation used for the edge
• mask visualization of the edge (can be EC_MASK_SHOW or EC_MASK_HIDE)
This function returns True on success and False otherwise.

Please note:
If the specified value for the parameter where is greater than or equal to the number of
edges in the segment list the edge will be added at the end of the segment list.

There is also a high level function for creating a complete object. This function is called
EcObjectCreate and has the following restrictions:
• exactly one feature object, one primitive and one segment are created
• no cluster objects can be created
• only two-dimensional coordinates are accepted

233
EC2007 ECDIS Kernel Programming Guide

• when creating an area object the last coordinate has to coincide with the first coordinate
The function EcObjectCreate takes the following parameters:
• cellid Identifier of a mapped cell
• dictinfo Pointer to an object dictionary context
• classname Object class token
• status Status of feature object
• attrstr Attribute tokens and values
• delimiter Delimiter used in attrstr
• coor Array of coordinates (latitude and longitude values)
• nocoor Number of coordinate pairs
• ptype Type of primitive (can be EC_P_PRIM, EC_L_PRIM or EC_A_PRIM)
• primitive Pointer to created primitive
The return value of this function is the handle of the newly created feature object. In
addition the handle of the corresponding primitive is returned.

11.5.2 Deleting Objects

The ECDIS Kernel also provides functions to delete a complete object or each object
component separately. These functions are called EcObjectDelete, EcFeatureDelete,
EcPrimitiveDelete, EcNodeDelete, and EcEdgeDelete. Each of these functions takes a handle of
the respective object component as only parameter and return True on success and False
otherwise.

Please note:
Only objects which have the EC_OS_DELETABLE flag set in the status may be deleted.

Some parameters and, if assigned, attributes of the deleted components can be stored in a
separate list of deleted objects. The memory of the deleted component inside the cell is
then not freed completely. This behaviour has to be explicitly set for each mapped cell. By
default the delete functions remove the respective object components completely, and free
all allocated memory.
The function EcCellSetDeleteMode is used to change the delete mode for a particular cell. The
parameters are:
• cellid Identifier of a mapped cell
• mode Selected delete mode of type EcDeleteMode (can be EC_DELOBJ_FULL or
EC_DELOBJ_TOLIST)
The objects are either fully deleted (EC_DELOBJ_FULL), which is the default value, or specific
information about the deleted objects is stored in a separate list (EC_DELOBJ_TOLIST). The
selected delete mode is stored in the structure EcCellId and is only valid as long as the cell is
mapped. In case the cell is unmapped the information about the delete mode is lost. When
mapping the same cell again later the default delete mode will be set.
234
 EC2007 ECDIS Kernel Programming Guide

When using the EC_DELOBJ_TOLIST delete method the list of deleted objects is filled. All the
deleted object components are of type EcDeletedObject, and the following information is
stored:
• former component type (see EcDeletedObjectType definition below for possible values)
• class token (only for former feature objects)
• group (only for former feature objects)
• object id (only for former feature objects)
• record ID (for all types)
• status (for all types)
• attribute list (only for former feature objects, nodes or edges)
• wide character attribute list (only for former feature objects)
The enumeration type EcDeletedObjectType can have following values:
• EC_DELOBJ_NOOBJECT = 0, (error)
• EC_DELOBJ_FEATURE, (feature object)
• EC_DELOBJ_P_PRIM, (point primitive)
• EC_DELOBJ_S_PRIM, (sounding cluster primitive)
• EC_DELOBJ_L_PRIM, (line primitive)
• EC_DELOBJ_A_PRIM, (area primitive)
• EC_DELOBJ_B_NODE, (bounding node)
• EC_DELOBJ_2D_NODE, (isolated node 2 dimensional)
• EC_DELOBJ_3D_NODE, (isolated node 3 dimensional)
• EC_DELOBJ_EDGE (edge)

Please note:
No relations to other components are stored in this list of deleted objects.

The list of deleted objects can be accessed with the functions EcDeletedObjectGetFirst and
EcDeletedObjectGetNext.
The function EcDeletedObjectGetFirst takes the cell ID of a mapped cell as only parameter and
returns the handle of the first element of the list of deleted objects. This is the last object
component that has been deleted in the specified cell by means of one of the functions
EcFeatureDelete, EcPrimitiveDelete, EcNodeDelete, and EcEdgeDelete, EcObjectDelete or
EcCellRemoveOrphans.
The function EcDeletedObjectGetNext takes a handle of the type EcDeletedObject as only
parameter and returns the next deleted object following the specified one in the list of
deleted objects.
By means of the function EcDeletedObjectGetNumber the number of elements in the list of
deleted objects can be retrieved for a given cell.
EXAMPLE:

235
EC2007 ECDIS Kernel Programming Guide

In the following example first all mariners notes are deleted. The the number of deleted
objects is determined by retrieving each component one by one, and the result is then
compared with the value returned by the function EcDeletedObjectGetNumber.
char *cellName = "7C5ABCDE.7CB";
EcCellId cellId;
EcFeature feature;
EcFindInfo fI;
EcDeletedObject dObj;
EcCoordinate lat, lon;

// read the dictionaries

if ((dictInfo = EcDictionaryReadModule(EC_MODULE_MAIN, NULL)) == NULL)
{ /* error handling */ }

// map cell with write access

if((cellId = EcCellMap(cellName, EC_ACCESSWRITE, 0)) == EC_NOCELLID )
{ /* error handling */ }

// set the delete mode to store the deleted objects in a list

EcCellSetDeleteMode(cellId, EC_DELOBJ_TOLIST);

// Search for all mariners notes

feature = EcQuerySpotCell(cellId, dictInfo, "marnot", "", '!', &fI,
EC_FIRST, &lat, &lon);
while (ECOK(feature))
{
// delete a feature object of the cell, it will be stored in the list
EcFeatureDelete(feature);

feature = EcQuerySpotCell(cellId, dictInfo, "marnot", "", '!', &fI,

EC_NEXT, &lat, &lon);
}

// get the number of deleted objects

int i = EcDeletedObjectGetNumber(cellId);
if (i >= 0)
{
int j = 0;
// get the first deleted object of the cell
dObj = EcDeletedObjectGetFirst(cellId);
while (ECOK(dObj))
{
++j;
// get the next deleted object of the cell
dObj = EcDeletedObjectGetNext(dObj);
}
if (i==j)
printf("OK: %d objects in delete list.\n", i);
else
printf("Something is wrong with this cell.\n");
}

236
 EC2007 ECDIS Kernel Programming Guide

// unmap cell
EcCellUnmap(cellId);

When retrieving the stored information about any deleted object it is usually important to
know of what type the deleted object is. The function EcDeletedObjectGetType is used to
determine the type of a deleted object component. This function takes a handle of the
deleted object as only parameter and returns its type. The return value of this function is of
type EcDeletedObjectType. Its possible values are described above.
For all deleted objects the identifiers and the status can be obtained. Depending on the type
of the deleted object the following functions can be used to retrieve the corresponding
information:
• EcDeletedObjectGetRecId to retrieve the record ID
• EcDeletedObjectGetStatus to retrieve the status
For former feature objects, nodes, and edges the attributes can be retrieved one by one with
the function EcDeletedObjectGetAttributes. It is also possible to search for a particular
attribute in the list of attributes of the deleted object. The function used for this purpose is
called EcDeletedObjectQueryAttribute.
In addition to the information mentioned above the following data can be obtained for
former feature objects:
• EcDeletedObjectGetObjectId to retrieve the deleted feature object’s ID.
• EcDeletedObjectGetClass to retrieve the class that the deleted feature object was derived
from.
• EcDeletedObjectGetGroup to retrieve the group that the deleted object belongs to.
• EcDeletedObjectGetAttributesW to retrieve wide character attributes one by one.
• EcDeletedObjectQueryAttributeW to search for a particular wide character attribute.
To permanently remove all information about the deleted objects from the cell a cleanup
has to be done by means of the function EcCellForceCleanUp.
Besides removing all deleted objects and reorganizing the cell by means of this function it is
also possible to completely remove single deleted object components from the list of
deleted objects.
The function EcDeletedObjectShred is used to remove an element from the list of deleted
objects of a given cell. This function takes the handle of the deleted object that is to be
completely removed as only parameter and returns True on success and False otherwise.

11.5.3 Modifying Objects

When creating new object components the most important parameters are passed to the
respective create functions. For these and all other parameters the values can be explicitly
set or changed once the object component exists. In the following section all functions
capable of modifying the object components are introduced. Since most of them are
analogous for the different components just one function is described in detail.

237
EC2007 ECDIS Kernel Programming Guide

[Link] Object Identifiers and Status

To set or change the record ID which is part of all object components the functions
EcFeatureSetRecId, EcPrimitiveSetRecId, EcNodeSetRecId and EcEdgeSetRecIdare used.
The record ID is used to uniquely identify the objects inside a cell, but is not needed for the
display or query of the cell objects. A unique record ID, as with S-57 edition 3 objects, can be
used to find particular object components within the cell. For example, when updating S-57
data the record ID is used to find the objects in a cell that are to be changed.

Please note:
Changing the record ID of S-57 objects will make updating these data impossible.

Each function takes a handle of the respective object component and the new record ID as
parameter. The record ID is of type UINT32, and the functions return True on success and
False otherwise.
The status of an object component is also not needed for the display or query. This
parameter can be used to store additional information. The functions EcFeatureSetStatus,
EcPrimitiveSetStatus, EcNodeSetStatus and EcEdgeSetStatusare used to set or change the status
of an object component.
Each function takes a handle of the respective object component and the status as
parameters. The status is of type EcStatus, which can have the following values:
• EC_OS_DELETABLE
• EC_OS_USERDEFINED,
• EC_OS_SYSTEMDEFINED
• or a bit-wise (or-) combination of these values
The functions return True on success and False otherwise.
Before an object can be deleted its status must be set to include the EL_OS_DELETABLE flag.

[Link] Feature Objects

The following functions are available only for feature objects.
The function EcFeatureSetObjectId sets or changes the feature object ID which is used in S-57
to relate feature objects. Unlike the record ID which is unique within a cell the feature object
ID is worldwide unique.

Please note:
Changing the feature object ID may result in the feature object ID no longer being
unique.

The function takes a handle of the feature object and the new feature object ID as
parameters. The object ID is of type EcFeatureObjectId and returns True on success and
False otherwise.
The function EcFeatureSetClass is used to change the class the feature object is derived from.
When creating a new feature object the class must be specified, so this function is used to

238
 EC2007 ECDIS Kernel Programming Guide

change the class of an already existing feature object. The function EcFeatureSetClass takes
the following parameters:
• feature Handle of the feature object
• dictinfo Pointer to an object dictionary context
• classname Object class token

Please note:
When changing the class of a feature object the attributes also must be changed to
correspond with the new class.

The function EcFeatureSetGroup sets or changes the group a feature object belongs to. In S-
57 there are two possible group values: 1 for skin of the earth objects and 2 for all others.

Please note:
Changing the group value of an S-57 object may result in the cell data becoming
inconsistent.

The areas inside a cell which contain data must be completely covered by group 1 objects
which may not overlap. The function takes a handle of the feature object and the new group
value as parameters. The group value is of type UINT32 and has to be within the range 0-
255. The function returns True on success and False otherwise.

[Link] Nodes
For nodes the type is of importance. It is set or changed with the function EcNodeSetType.
This function takes a handle of the node and the new type as parameters. The type is
EcNodeType, which can have the following values:
EC_ISOLATED_NODE or
EC_BOUNDING_NODE.
The function returns True on success and False otherwise.

[Link] Attributes
For feature objects and segments (nodes and edges) there are functions available for setting
attributes. With the following functions new attributes can be added to the already existing
list of attributes of a feature object or a segment. If any of the specified attributes already
exist in the current list of attributes their values will be overwritten.
• EcFeatureSetAttributes
• EcNodeSetAttributes
• EcEdgeSetAttributes
All these functions are very similar. They have the following parameters:
• handle Handle of the feature object, node or edge
• dictinfo Pointer to an object dictionary context
• attrstr Attribute string

239
EC2007 ECDIS Kernel Programming Guide

• delimiter Delimiter used in attrstr

The parameter attrstr consists of a sequence of attribute tokens and attribute values, which
are separated by the delimiter specified in the fourth parameter.
SevenCs recommends to use ‘|’ (ASCII 124) as delimiter because it is seldom used in names,
text or numeric expressions.
The function EcFeatureSetAttributesW which is used to set or change wide character
attributes for feature objects has a slightly different parameter list:
• feature Handle of the feature object
• dictinfo Pointer to an object dictionary context
• attrtoken Attribute token
• attrvalue Wide character string for the specified attribute
With the previous functions as many attributes as desired can be set or changed at once, but
with this function the wide character attributes must be set one by one.
It is not only possible to add attributes to the list of attributes of an object component, but
also to remove single attributes from that list or to delete the entire list of attributes.
The following functions remove a single attribute from the list of attributes of a given
feature object, node or edge:
• EcFeatureRemoveAttribute
• EcNodeRemoveAttribute
• EcEdgeRemoveAttribute
The parameters are:
• handle Handle of the feature object, node or edge
• dictinfo Pointer to an object dictionary context
• attrtoken Attribute token
The attribute that is to be deleted is specified by its token, and the functions return True on
success and False otherwise.
The following functions completely remove the entire list of attributes of the given feature
object, node or edge:
• EcFeatureRemoveAllAttributes
• EcNodeRemoveAllAttributes
• EcEdgeRemoveAllAttributes
These functions take a handle of the respective feature object, node or edge as only
parameter, and return True on success and False otherwise.

[Link] Geographic Position

The geographic position of an object is solely stored in its segments. When creating a new
node or edge the geographic position is set. To alter this position the following functions can
be used:

240
 EC2007 ECDIS Kernel Programming Guide

The function EcNodeSetPosition is used to set the latitude and longitude of a node. The
parameters are:
• node Handle of the node
• lat Latitude of new position (in degrees)
• lon Longitude of new position (in degrees)
This function returns True on success and False otherwise.

Please note:
If the position of a bounding node is changed the corresponding vertex positions of the
related edges will be automatically changed as well.

The function EcNodeSetThirdDimension is used to change the depth value of a 3 dimensional

node. This function takes a handle of the node and the new depth value as parameters and
returns True on success and False otherwise. If a 2 dimensional node is passed to this
function it will return False.
The geographic position of an edge is specified by the list of vertices, where each vertex has
at least a latitude and longitude coordinate. When creating a new edge a list of vertices must
be specified. To make changes in this list the following functions can be used:
• EcEdgeAppendVertex
• EcEdgeInsertVertex
• EcEdgeRemoveVertex
With the function EcEdgeAppendVertex a new vertex can be added to the end of the vertex
list. This function takes a handle of the edge and an array of coordinates as parameters. The
coordinates are of type EcCoordinate, and the amount of elements in the array depends on
the dimension of the vertices in the vertex list. However, the first two coordinates are
always latitude and longitude of the vertex.
By means of the function EcEdgeInsertVertex a new vertex can be added to the vertex list at
any position. Therefore this function also takes as parameters the handle of the edge and an
array of coordinates as well as the index where the vertex is to be inserted into the list of
vertices. The index 0 indicates that the new vertex will be inserted as the first vertex of the
list.
To remove a vertex from the list of vertices the function EcEdgeRemoveVertex is used. This
function takes as parameters the handle of the edge and the index of the vertex that is to be
removed. The index 0 indicates that the first vertex will be removed.
To alter the coordinates of a vertex in the list of vertices the function EcEdgeSetVertexPosition
can be used. With this function the position of a particular vertex can be altered without
adding or removing any vertices of the vertex list. The parameters of this function are:
• edge Handle of the edge
• index Index of the vertex to be changed (0 indicates first)
• coor Array of new coordinates

241
EC2007 ECDIS Kernel Programming Guide

If the position of the first or last vertex of an edge is changed and this edge has a relation to
a starting or ending bounding node respectively, the position of the corresponding bounding
node will be automatically changed as well.
To change the complete list of vertices of an edge the function EcEdgeSetPosition is used. This
function replaces the current vertex list with a new list of vertices. The parameters are:
• edge Handle of the edge
• coor Array of new coordinate tuples
• ncoor Number of coordinate tuples in the array coor
Relations to bounding nodes will be deleted by this function.

[Link] Relations
When creating a complete object the relations between the different object components
must be specified, e.g. a feature object has to be linked with the primitive.
However, a relation that is not mentioned in that chapter is the relation between two
feature objects. The function EcFeatureRelate is used to create a specified type of relation
between two feature objects. The parameters are:
• feature1 Handle of the original feature object
• relation Type of relation
• feature2 Handle of the related feature object
The relation is of type EcFeatureRelation and may have the following values:
• EC_MASTER_OF or EC_SLAVE_OF,
• EC_BELONGS_TO or EC_HAS_A,
• EC_CONSISTS_OF or EC_IS_PART_OF,
• EC_HAS_MEMBER or EC_IS_MEMBER_OF,
• EC_IS_RELATED_TO
The function returns True on success and False otherwise.
To remove a particular or all relations of a feature object to other feature objects the
function EcFeatureRemoveRelation is used. This function takes the same three parameters as
EcFeatureRelate, and removes the relation specified thereby. In case the second object
handle is empty all relations of the first feature object will be removed regardless of the
relation type.
In chapter 11.5.1 Creating Objects it is described how the relations between the different
objects are created. With following functions the relations can be removed or modified.
To remove the relation between a feature and its primitive the function
EcPrimitiveRemoveFromFeature is used. The parameters of this function are the handles of
the feature object and the primitive.
To remove the relation between a primitive and its node the function
EcNodeRemoveFromPrimitive is used. This function takes the handles of the primitive and the
node as parameters.

242
 EC2007 ECDIS Kernel Programming Guide

To remove the relation between a primitive and one of its edges the function
EcEdgeRemoveFromPrimitive is used. This function takes the handle of the primitive and the
index of the edge in the edge list as parameters. The index 0 indicates the first edge in the
edge list.
All relations mentioned above are bi-directional. For example, if there is relation between a
node and a primitive it is possible to retrieve the related primitive if the node is given, and to
retrieve the related node if the primitive is given. When calling any of these functions which
remove a relation both directions will be removed.
A special relation between object components is the relation between an edge and a
bounding node. This relation only exists in one direction, coming from the edge, i.e. it is not
possible to retrieve the edge a given bounding node is related to. The function that creates
such a relation is called EcEdgeSetBoundingNode. The parameters are:
• edge Handle of the edge
• ori First or last bounding node
• node Handle of the node
The parameter ori specifies whether the given bounding node is the beginning or end
bounding node of the edge. The values are EC_FORWARD for the beginning and EC_REVERSE
for the end bounding node. To remove a bounding node the function is called with an empty
node handle.

Please note:
This function implicitly modifies the first or last vertex of the edge’s vertex list. If an
existing bounding node is replaced the position of the respective vertex will change
accordingly, if a new node is set a vertex will be appended, and if a bounding node is
removed the corresponding vertex will be removed as well.

243
EC2007 ECDIS Kernel Programming Guide

12 Extended Functionality
12.1 Manual Chart Installation
For standard applications like ECDIS, VTS or CMS SevenCs recommends to use the high level
EcDENC… functions for chart installation (see chapter 6.5). However, there are low level
functions with which chart handling can be implemented as well.

[Link] Manual SENC Catalogue Handling

The SENC catalogue can be created manually by the function EcCellCreateCatalogue.
In case the scope of the SENC database is very large the execution time of these functions
must be taken into consideration.
When adding, deleting or changing single cells of the SENC database the cell catalogue can
be matched to the current state of the SENC database using the function
EcCellUpdateCatalogue.

[Link] Catalogue List

The catalogue list is an auxiliary structure that serves as a link between the cell catalogue
and the functions used to load cells. This catalogue list can be created with the function
EcCellCreateCatalogueList, and the allocated memory is freed with EcCellFreeCatalogueList.
When synchronizing the cell catalogue with the SENC the catalogue list must be created
again.

[Link] Reading SENC Catalogue Content

The content of the SENC catalogue, i.e. information about the cells, can be read with the
function EcCellGetCatalogueInfoExt. Please refer to the example readcat for more
information.

12.2 Manual Chart Display

As described in chapter 6.6 and illustrated in Figure 3 the four steps viewport definition,
chart loading, chart symbolization and chart drawing are all combined into the high level
function EcDraw[NT|X11]DrawChart which SevenCs advises to use for standard chart display
systems.
However the four steps can be separated from each other using the low level function
described in the following chapters. This allows a greater flexibility of the chart display
process.
It lies in the responsibility of the application builder to implement the functions at the
correct positions and to call them at the right time.

244
 EC2007 ECDIS Kernel Programming Guide

12.2.1 Viewport Definition

The viewport can be set with the function EcDrawSetViewport which takes the following
parameters:
• view Pointer to a view context
• centerlat Latitude of new center position
• centerlon Longitude of new center position
• range Range of new viewport in nautical miles
• heading Orientation of display in nautical degrees
By default the center of the viewport is in the center of the drawing area. To be able to
realize an off-center chart display the center of the viewport can be positioned anywhere
within the drawing area, and even outside the drawing area. The function
EcDrawSetViewportCenter is used to set the virtual viewport center of the given view. This is
the position on the drawing area to which the viewport parameters refer. The geographical
position passed to EcDrawSetViewport will be matched to this point which is also the center
of an optional rotation.

12.2.2 Chart Loading

This selection process described in the previous chapter is part of the functions
EcDENCLoadViewByAreaExt and EcChartLoadViewByAreaExt.
SevenCs recommends to use the function EcDENCLoadViewByArea for standard applications
like ECDIS or VTS. This function loads cells into a view for visualization. It supports the
automatic chart loading concept (see previous chapter). The function takes the following
parameters:
• view Pointer to a view context, previously created with EcChartViewCreate.
• denc Pointer to a EcDENC structure, previously created with EcDENCCreate
• minX, minY Minimum x-y-coordinates of viewport in pixel
• maxX, maxY Maximum x-y-coordinates of viewport in pixel
• ecUsage Usage of cells to be loaded
• loadMode Loading mode, either EC_LOAD_COVERAGE or EC_LOAD_USAGE
The parameters minX, minY, maxX, and maxY specify the corners of the rectangle on the
screen into which the chart image is drawn. The area of the earth's surface to be displayed is
defined by the specified viewport. The function also needs the usage of the cells to be
visualized. In case the loadMode is defined as EC_LOAD_COVERAGE all usages less than the
defined usage will be considered for the chart display, e.g. a defined usage Coastal will
consider the usages Coastal, General and Overview for the chart display. The usage which
will be passed to the function EcDENCLoadViewByArea has to be determined by the function
EcDrawScaleToUsage in advance. This is necessary to avoid the display of very high dense big
scale charts for overview purposes.

245
EC2007 ECDIS Kernel Programming Guide

The loading mode which indicates that either only cells of the given usage are loaded or cells
with less detailed data are loaded, too, in order to cover the entire viewport.
For special application the loadMode can also be defined as EC_LOAD_USAGE. In that case
only the defined usage will be considered for the chart display.
EcChartLoadViewByArea is the corresponding low level function for special applications. It
takes the same parameters except that as second parameter a pointer to the chart catalogue
context is passed instead of the pointer to the EcDENC structure.
EcChartUnloadView removes all cells from the view. This function is rarely needed, and it
should not be used before calling the function EcChartLoadViewByArea. Otherwise this would
cause a symbolization of all cells which are loaded into the view thus entailing an
unnecessary loss of speed during the visualization.
As stated above internally a virtual web is used to determine the cells required to cover the
viewport. The extension of a single mesh is fixed, i.e. the functions EcChartLoadViewByArea
and EcDENCLoadViewByArea work with a fixed width of 16 and fixed height of 12 pixels.

Please note:
In the very rare cases that the extension of a displayed cell is less than the fixed mesh it
might happen that a cell is completely covered by one mesh. In this case the cell will not
be considered by the loading process. For that purpose there are extended versions of
the cell loading functions (see below).

With the functions functions EcChartLoadViewByAreaExt2 and EcDENCLoadViewByAreaExt2 the

minimum size of a cell can be defined.

[Link] Single Cell Loading

Besides the automatic chart it is also possible to manually load cells into the view. This is
usually the case when using overlay cells in addition to the charts from the SENC database
which have been loaded previously with the automated chart loading (see previous chapter)
To manually add cells to the view the respective cell first must be mapped with the function
EcCellMap, and then loaded into the view using the function EcChartAssignCellToView.
The function EcChartUnAssignFromView is used to remove the cell from the view. However,
this function does not take care of the un-mapping of the cell. This is the responsibility of the
application by using the function EcCellUnmap.
Using both the manual and the automatic cell loading concept at the same time may cause
unforeseen conditions, because the un-mapping of a cell is handled by the ECDIS Kernel for
the automatic loading processes, and by the application for the manual cell loading
processes.
However, in some exceptional cases it is desired that a particular cell (e.g. for mariners
information objects) is controlled by the application, and should not be influenced by the
automatic chart loading process. For this purpose the ECDIS Kernel supplies the simple
mechanism called cell locking. When locking a cell its Cell Entry is permanently placed in the
Cell List. This means that the automatic cell loading process cannot move the Cell Entry into
the Cell Cache.
The function EcChartCellLock is used to change the locking state of a given cell and takes the
following parameters:

246
 EC2007 ECDIS Kernel Programming Guide

• view Pointer to a view context

• cellId Identifier of the cell to be locked
• lockFlag Locking state
To remove the locked cell from the view the function EcChartUnAssignFromView can be used.
The function EcChartUnloadView removes all cells of the given view, and un-maps them. This
function should be used to clean up a view before deleting it.

12.2.3 Chart Symbolization

Before a chart can be drawn it has to be symbolized, i.e. a Display List must be created for all
objects contained in the chart.
When changing the Mariner’s Settings all cells assigned to the view must be symbolized
because these changes influence the entire chart display, not only one cell.
When a new cell is loaded into the view because the viewport has changed only the new cell
needs to be symbolized. The Display Lists of all other cells in the view are still valid and can
be reused for drawing the chart display.
A cell must be symbolized in case
1. it has not been symbolized before (viewport has changed, i.e. no Display List exists for
the cell).
2. the Mariner’s Settings which influence the chart display have been changed.
3. objects have been added to or deleted from the cell.
4. the highlight status has been changed for one or more objects in the cell.
These first two reasons for symbolizing a cell are evaluated automatically by the ECDIS
Kernel software when using the function EcChartSymbolizeView with the parameter
symbolForce set to False. In that case only the cells that do not have a valid Display List will
be symbolized.
If this function is called with the parameter symbolForce set to True all cells loaded in the
view will be symbolized. As a result the Cell Cache will be flushed because the Display Lists
stored there are no longer valid.
In case of the third reason the cell or cells have to be symbolized with the function
EcChartSymbolizeCell. The parameters of this function are:
• view Pointer to view structure
• cellid Identifier of the cell to be symbolized
The specified cell must be assigned to the given view.
To symbolize a certain set of cell of a view the function EcChartSymbolizeCells can be used.
The parameters are:
• view Pointer to view structure
• cellids Identifiers of the cells to be symbolized
• nCellids Number of cells identifiers

247
EC2007 ECDIS Kernel Programming Guide

In case of the fourth reason the two functions EcChartSymbolizeFeature and

EcChartSymbolizeFeatures can be used. These functions are useful if the display of only few
objects of a cell have been changed. It should be considered, however, whether it is faster to
symbolize single feature objects or the entire cell. The related cell already must have been
fully symbolized before.

12.2.4 Chart Drawing

After the view or cell or feature has been symbolized the chart image has to be drawn.
EcDraw[X11|NT]DrawCells draws all cells that are given in the parameter list.
EcDraw[X11|NT]DrawView draws all cells that are currently assigned to the specified view.

12.3 Chart Pick Report

Most chart display systems allow the user to query for the details of chart objects. Usually
the user picks at a certain position and the details are then displayed in the so-called pick
report. To get the information about objects at a specific position the function
EcQueryPickVisible is used.
In order to avoid multiple entries of one feature class due to more than one usage loaded for
the view the function EcQueryPickFilter can be used.
To disable the listing of chart objects which are not displayed due to some specific chart
settings a further filter can be applied with the function EcQueryFilterFeatures.
The following example shows the framework for the pick routines. It has to be filled with the
functions described in the previous chapters. Another example is given in the Qt based
example program showDENC and showENC.
EcCellId *cids = NULL;
EcDictInfo *dictInfo;
EcFeature *fList = NULL;
EcFeature *ffList = NULL;
EcFindInfo fI;
EcAttributeToken aTok;
EcView *view;
int pickX, pickY, cellNum, fNum, ffNum;
int pickRad = 7;

/* the dictionary context and the view have been

created in previous steps */

// get all cells loaded in the view

cellNum = EcChartGetLoadedCellsOfView(view, &cids);

if (cellNum <= 0)
{ /* error handling */ }

// get all features located at pick position

248
 EC2007 ECDIS Kernel Programming Guide

fNum = EcQueryPickVisible(view, dictInfo, pickX, pickY, pickRad,

"", "", '!', cids, cellNum, &fList);
if (fNum > 0)
{
// get only the features of the "best usage"
ffNum = EcQueryPickFilter(dictInfo, fList, fNum, &ffList);
EcFree((void*)fList);
}

if (ffNum > 0)
{
for (int i=0; i<ffNum; i++)
{
/* Query the feature details, e.g. with
EcObjectGetLocation
EcFeatureGetClass
EcDictionaryTranslateObjectToken */

// get the attributes of the feature

Bool result = EcFeatureGetAttributes(ffList[i], dictInfo, &fI,
EC_FIRST, aTok, sizeof(aTok));
while (result)
{
/* Query the attribute details, e.g. with
EcDictionaryTranslateAttributeToken
EcDictionaryTranslateAttributeValue */
result = EcFeatureGetAttributes(ffList[i], dictInfo, &fI,
EC_NEXT, aTok, sizeof(aTok));
}

}
EcFree((void*)ffList);
}
EcFree((void*)cids);

Please note:
The attributes NOBJNM, NINFOM, NTXTDS and NPLDST are so-called national attributes
and may contain non Western European Latin Characters.

12.4 Referenced Files

The S-57 standard allows to store longer textual information (e.g. longer chart notes, tables
or paragraphs from sailing directions) outside of the S-57 file in so-called referenced files.
The same applies to pictorial information. The names of referenced files are stored in certain
attributes of the respective object.

249
EC2007 ECDIS Kernel Programming Guide

The following example shows how to retrieve the location of the referenced files within the
DENC directory structure.
void getFileReferences(EcCellId cellId, const EcDictInfo *dictInfo,
EcDENC *denc)
{
char attrStr[256], attrToken[256], fileName[256];
Bool ok;
EcFeature feature;
EcFindInfo fI;
feature=EcFeatureGetFirst(cellId);
while (ECOK(feature))
{
ok=EcFeatureGetAttributes(feature, dictInfo, &fI, EC_FIRST,
attrStr, sizeof(attrStr));
while (ok)
{
// check for empty or unknown value
if (strlen(attrStr) != EC_LENATRCODE)
{
strncpy(attrToken, attrStr, EC_LENATRCODE);
attrToken[EC_LENATRCODE]=(char)0;
/* check for textual reference ("TXTDSC" or "NTXTDS") */
if (!strncmp(attrToken, "TXTDSC", 6) ||
!strncmp(attrToken, "NTXTDS", 6))
{
strcpy(fileName, &attrStr[EC_LENATRCODE]);
if (EcDENCGetPath(denc, attrToken, fileName,
sizeof(fileName), False))
{
// do something
}
}
/* check for picture reference ("PICREP") */
if (!strncmp(attrToken, "PICREP", 6))
{
strcpy(fileName, &attrStr[EC_LENATRCODE]);
if (EcDENCGetPath(denc, attrToken, fileName,
sizeof(fileName), False))
{
// do something
}
}
}
ok=EcFeatureGetAttributes(feature, dictInfo, &fI, EC_NEXT,
attrStr, sizeof(attrStr));
} // while
feature=EcFeatureGetNext(feature);
} // while
}

250
 EC2007 ECDIS Kernel Programming Guide

12.5 User-Defined Viewports

In some cases full control over the transformation matrix of the affine transformation (see
chapter 6.6.3) is needed. This is necessary in case other information shall be superimposed
by the ECDIS-Display, and external projections shall be utilized (see next chapter).
By using the function EcDrawSetTransformation the transformation matrix can be defined.
Calculating the single coefficients then is within the responsibility of the application.
An example of a user-defined viewport is given in chapter 12.8.

Please note:
The inverse transformation matrix is always created automatically by the EC2007ECDIS
Kernel.

Using external methods constitutes another way to control the transformation. External
methods can be transferred to the EC2007ECDIS Kernel by means of the function
EcDrawSetTransformProc.

Please note:
In case external transformation methods are used the function EcDrawInitViewport must
be called whenever the viewport parameters have been changed.

12.6 User-Defined Projections

In the ECDIS Kernel it is also possible for an application to use its own projection to produce
a chart display. The function EcDrawSetLatLonFunctions sets external projection functions to
be used in the ECDIS Kernel. There are always two functions passed to the Kernel, one for
the forward projection, and one for the reverse projection. The type EcProjectionProc is
defined in the Kernel for these functions:
typedef int(*EcProjectionProc)(double p1, double p2,
double *p3, double *p4, void *p5);

The forward function will be called with the following parameter:

p1 (in) latitude [ radians (-PI/2 <= p1 <= PI/2) ]
p2 (in) longitude [ radians (-PI <= p1 <= PI) ]
p3 (out) easting [ units depend on the projection ]
p4 (out) northing [ units depend on the projection ]
p5 (in) userData passed to EcDrawSetLatLonFunctions
The reverse function will be called with the following parameter:
p1 (in) easting [ units depend on the projection ]
p2 (in) northing [ units depend on the projection ]
p3 (out) latitude [ radians (-PI/2 <= p1 <= PI/2) ]

251
EC2007 ECDIS Kernel Programming Guide

p4 (out) longitude [ radians (-PI <= p1 <= PI) ]

p5 (in) userData passed to EcDrawSetLatLonFunctions

Please note:
Changing the projection does not affect the viewport settings. Panning or zooming is still
realized by calling the function EcDrawSetViewport. Changing the projection parameters
lies within the responsibility of the application.

The function EcDrawCartesianToXy transforms cartesian coordinates (the result of a

projection) into device coordinates. This may be necessary when an external projection is
used and an overlay is to be drawn by the application. In this case coordinates of the overlay
do not have to be projected again but can be stored for later use.
The following example shows the use of the Lambert Conformal Projection. The structure
Lambert contains all information about the projection parameters. With the function
LambertInit the projection parameters are set, the functions LambertForward and
LambertInvers are the external projection functions passed to the ECDIS Kernel.
typedef struct _Lambert
{
double false_easting;
double false_northing;
double center_lon;
double r_major;
double e;
double ns;
double f0;
double rh;
}Lambert;

int LambertInit(Lambert *lbt, double a, double b,

double lat1, double lat2, double clat, double clon,
double f_e, double f_n);
int LambertForward(double lat, double lon, double *easting,
double *northing, void *lambert_data);
int LambertInvers(double easting, double northing,
double *lat, double *lon, void *lambert_data);

Lambert lambert;

With the call of LambertInit the projection is initialized. The function call
EcDrawSetLatLonFunctions passes the forward and reverse projection functions and a pointer
to an arbitrary piece of data containing the information about the projection (Lambert
structure) to the ECDIS Kernel. The last three parameters of this function specify the
particular projection behaviour:
• poleValid specifies whether latitude of 90 degree (PI/2) is valid for calculation.
• loxoStrait specifies whether the loxodrome is a strait line in this projection
• rightHand specifies whether the result of the projection is a right-hand system.
To switch back to an internal projection EcDrawSetProjection is used.

252
 EC2007 ECDIS Kernel Programming Guide

// initialize the Lambert Conformal Projection

LambertInit(&lambert,
6378137.0, // major semi axis of WGS84 spheroid
6356752.3142, // minor semi axis of WGS84 spheroid
58*M_PI/180, // standard parallel farther from equator
44*M_PI/180, // standard parallel nearer to equator
lat*M_PI/180, // central parallel (projection center)
lon*M_PI/180, // central meridian (projection center)
0, // false easting
0); // false northing
// switch to external Lambert projection
EcDrawSetLatLonFunctions(view, LambertForward, LambertInvers,
(void*)&lambert, False, False, True);
…
// switch back to internal Mercator projeciton
EcDrawSetProjection(view, EC_GEO_PROJECTION_MERCATOR, lat,lon);

The next example shows how the ECDIS Kernel can be used to mix a raster image with a
vector overlay. First we assume that we have a geo-referenced raster image, and that there
are two functions to convert the image coordinates into geographic coordinates and vice
versa. These functions are of the type EcProjectionProc. Their prototypes are:
void LatLonToRaster(double lat, double lon, double *x,
double *y, void *client_data);
void RasterToLatLon(double x, double y, double *lat,
double *lon, void *client_data);

The problem to solve is to determine the viewport settings for matching a vector overlay.
EcDrawSetLatLonFunctions(view, LatLonToRaster, RasterToLatLon,
NULL, False, False, False);

First we set the conversion functions as external projection functions.

Please note:
The y-coordinate on a raster image increases from top to bottom.

Next the viewport has to be set with a given geographic position. Width and height are the
dimensions of the viewport. In this example zoom is not supported on the raster image.
Bool SetRasterViewport(EcView *view, EcCoordinate lat, EcCoordinate lon,
int *r_offs_x, int *r_offs_y)
{
double x_c, y_c;
EcTransformationMatrix matrix;

// get image coordinates of center position

LatLonToRaster(lat, lon, &x_c, &y_c, NULL);

// fill the transformation matrix

matrix.m12 = matrix.m21 = 0.0;
matrix.m11 = matrix.m22 = 1.0;

253
EC2007 ECDIS Kernel Programming Guide

matrix.m31 = -x_c + width/2;

matrix.m32 = -y_c + height/2;

// get offset for raster drawing

*r_offs_x = x_c - width/2;
*r_offs_y = y_c - height/2;

// set the view port

return EcDrawSetTransformation(view, &matrix);
}

12.7 Globe
The EC2007 ECDIS Kernel includes special globe and harbor data. These data are used to
display the coastlines of the entire world on a globe. The position of several harbors can be
indicated by a point symbol on this globe. In addition the data are well suited to display a
rough overview of the world with the outlines of the cells that are available in the DENC
structure.
The data are stored in the two SENC files world4.7CB and places4.7CB in the default directory
$EC2007DIR\data\globe. The globe SENC are treated as every other SENC.
For a sample implementation please refer to the example program showGlobe.

12.7.1 Displaying the Globe and Harbors

In addition to the standard steps, i.e.
• Reading the dictionary
• Creating a new view
• Initialize drawing functions
• Create pixmap and device context
• Read colors and set new color palette
the following globe specific steps have to be implemented.
• Set the new globe viewport (no need to initialize the settings or symbolize a chart)
• Set the scale threshold value for drawing harbors dependent on the globe radius
• Clear the drawing area; realized in a sub-function
• Draw globe data into the device context
• Draw harbor data into the device context
• Create a list box and insert all harbor names contained in the harbor file.
• Free the resources

254
 EC2007 ECDIS Kernel Programming Guide

Load the globe and harbor data:

The functions EcGlobeLoadData and EcGlobeLoadPlaceData load the globe data and harbor
data files respectively. They both take three parameters, a pointer to the view structure
which has first been created with EcChartViewCreate, a dictionary context gained by
EcDictionaryReadModule, and the pathname specifying the directory in which the globe and
harbor cells are located. If the pathname is NULL the functions will look for the data files in
the default directory $DATA_7CS/Golbe. The function EcGlobeLoadData must be called before
any other EcGlobe… functions can be used. Also, the resources allocated by these functions
are freed by the function EcGlobeFreeData or EcGlobeFreePlaceData respectively.
EcDictInfo *dictinfo;
EcView globeview;

// the dictionary context and the view have been created in previous
steps

...

if (!EcGlobeLoadData(globeview, dictinfo, NULL))

// error handling

if (!EcGlobeLoadPlaceData(globeview, dictinfo, NULL))

// error handling

...

EcGlobeFreeData(globeview);
EcGlobeFreePlaceData(globeview);

Set the Projection and Viewport

Before setting the viewport the projection of the globe must be specified. The function
EcGlobeSetProjection takes a pointer to the view and the projection as parameters. Values
allowed for globe projections are: EC_GLOBE_ORTHOGRAPHIC, EC_GLOBE_HAMMER,
EC_GLOBE_MOLLWEIDE, and EC_GLOBE_ECKERT.
The function EcGlobeSetViewport sets the new viewport for the next globe drawing. The
parameters needed are a pointer to the view structure, the coordinates of the center
position on the globe in degrees, the coordinates of the globe center inside the viewport in
pixel, and the radius of the globe. For example, by placing the globe on the edge of the
viewport only half the globe is displayed in the window. However, to get the best display of
the globe data it is recommended to place the center of the globe in the center of the
viewport.
EcGlobeSetProjection(globeview, EC_GLOBE_ORTHOGRAPHIC);
EcGlobeSetViewport(globeview, latglobe, longlobe,
PIXMAP_X/2, PIXMAP_Y/2, radiusglobe);

Draw Globe and Harbor Data into the Device Context

Before the harbor data are drawn the minimum scale of the harbor data should be
calculated. The minimum scale also called SCAMIN is an attribute of the harbor data which

255
EC2007 ECDIS Kernel Programming Guide

indicates the minimum scale at which the harbor is shown. When decreasing the scale, i.e.
zooming out the harbor will no longer be displayed in order to avoid cluttering of data at a
very small scale. The SCAMIN value that is stored is the reciprocal of the minimum scale at
which the harbor is displayed. The function EcGlobeNTDrawPlaces additionally takes a
scaleThreshold value as a parameter. It is the responsibility of the programmer to pass the
appropriate scaleThreshold value for the current scale at which the globe is displayed. Since
the display scale is not known the radius of the globe is used to determine an appropriate
scaleThreshold value in the example. At the moment the harbor data contain three different
SCAMIN values: 42,000,000 for important harbors, 7,500,000 for less important harbors, and
5,000,000 for unimportant harbors. When zooming in the radius of the globe increases, and
more harbours will be displayed.

Please note:
The used radius and scale threshold values are randomly chosen and are purely based on
the appearance of the globe and harbor data in the sample program showGlobe.

The functions EcGlobe[NT|X11]DrawGlobe and EcGlobe[NT|X11]DrawPlaces draw the globe and

harbour data into the specified device context using the previously set viewport. The
parameters are a pointer to the view structure and the device context. The function
EcGlobe[NT|X11]DrawPlaces additionally takes a scaleThreshold value as a parameter.
HDC globeDC;
int scaleThreshold;

if (radiusglobe>2500)
scaleThreshold = 1000000; // all harbors are displayed
else if (radiusglobe>300)
scaleThreshold = 5000000; // unimportant harbors are not displayed
else if (radiusglobe>70)
scaleTHreshold = 10000000; // only important harbors are displayed
else
scaleThreshold = 50000000; // no harbors are displayed

if (!EcGlobeNTDrawGlobe(globeview, globeDC))
return FALSE;

if (!EcGlobeNTDrawPlaces(globeview, scaleThreshold, globeDC))

return FALSE;

Create a List Box and Insert All Harbor Names:

To offer the user a harbor selection box the function EcGlobeFindAnyPlace can be used to
retrieve all the names of the harbors from the harbor file one by one. To indicate a chosen
harbor on the globe view, the position can be queried with EcGlobeFindPlaceByName.
If the corresponding country of a harbor shall be considered as well the extended functions
EcGlobeFind...Ext can be used.
EcFindInfo findInfo;
Bool result = True;
char name[64];
EcCoordinate lat, lon;

256
 EC2007 ECDIS Kernel Programming Guide

int scamin;

// get the first harbor name

result = EcGlobeFindAnyPlace(globeview, name, sizeof(name),
&lat, &lon, &scamin, EC_FIRST, &findInfo);

while (result)
{
// get the next harbor name
result = EcGlobeFindAnyPlace(globeview, name, sizeof(name),
&lat, &lon, &scamin, EC_NEXT, &findInfo);
}

// let the user select a harbor

...

// get the position from the harbor file

EcGlobeFindPlaceByName(globeview, name, &lat, &lon, &scamin);

// set the viewport to the harbors position and redraw the view

12.7.2 Displaying the Globe and SENC Coverage

As mentioned above the globe can be used to select a geographic area of which the cells of
the SENC are loaded. The high-level function EcGlobe[X11|NT]DrawCoverage is used to draw
the coverage information contained in the specified catalogue list on the globe. This is an
easy way to indicate where SENC data are available.

12.7.3 Displaying the Globe and Routes

The function EcGlobe[X11|NT]DrawRoutes can be used to display all legs and waypoints
contained in the specified cell on the globe. The function EcChartSetShowAlternateRoute may
be used to toggle the display of alternate (not planned) objects.

12.7.4 Searching Nearest Harbor

To retrieve a harbor in the vicinity of a given position the function EcGlobeFindPlaceByPosition
is used. The returned harbor is the one nearest to the specified position within the given
radius.

12.7.5 Other Globe Functions

The ECDIS Kernel also includes two functions to draw and fill rectangles and one function to
draw polygons on the globe. These functions are EcGlobe[X11|NT]DrawRectangle,
EcGlobe[X11|NT]FillRectangle, and EcGlobe[X11|NT]DrawPloygon, respectively.

257
EC2007 ECDIS Kernel Programming Guide

Apart from drawing on the globe it might also be necessary to convert device coordinates of
the screen into latitude and longitude on the globe and vice versa. The two functions
EcGlobeXyToLatLon and EcGlobeLatLonToXy are provided to perform these conversions. For
example, when allowing panning of the globe or realizing marking of an area on the globe
using the mouse, the device coordinates obtained from the mouse have to be converted into
the corresponding latitude and longitude on the globe.
As mentioned above the harbor data are contained in a SENC, where each harbor is stored
as a place object. This place data can also be loaded and displayed together with other SENC
data. In the previous example showglobe the harbors were displayed on the globe and their
names in a list of harbors. As described in the example, before accessing these data the
function EcGlobeLoadPlaceData must be called, and the resources must be freed with the
function EcGlobeFreePlaceData if no longer needed.
The place data can be modified, too. With the function EcGlobeAddPlace a new harbor can be
added to the place data, and with the function EcGlobeRemovePlace a harbor can be deleted
from the place data.

12.8 World Data Set

SevenCs provides a small scale dataset for overview purposes. This dataset is not intended
for navigation but shall fill gaps in case at a certain location no charts are available.
The dataset consists of 90 SENC files covering the whole world.

The content is derived from the following sources:

Coastlines World Vector Shoreline (WVS) 1:250.000, generalized

Depth Contours Gebco Edition 2003
[Link]/products/bodc_products/gebco

258
 EC2007 ECDIS Kernel Programming Guide

Exclusive Economic Vlaams Instituut voor de zee (VLIZ), 2009,

Zones [Link]/vmdcdata/marbound
Ice areas NOAA for Arctic (Summer and winter 2006), Gebco for Antarctic
National borders, UKHO Paper Chart No 4000, 2005, 1:45 Mio
country and sea area
names
National borders and Exclusive Economic Zones are updated as required.
Since this world dataset is very detailed there might be problems with the display
performance at very small scales, i.e. less than 1:10 Mio or ranges bigger than 1000 sm.
That is why SevenCs provides another less detailed world data set and two copies of the
detailed world data set. In the first copy all SENCs are defined as “Usage 1”, i.e. overview.
They are located in %EC2007DIR%\data\World\2Mio_Usage1. In the other copy all SENCs are
define as “usage 2”, i.e. general. They are located in %EC2007DIR%\data\World\2Mio_Usage2.
In case of performance problems SevenCs recommends to use the low detailed world
dataset, which is located in %EC2007DIR%\data\World\12Mio_Usage1 together with the
detailed usage 2 world data set.

Please note:
Make sure that the two different usage 1 data sets are NOT used together.

12.9 World Overview

In case a world overview shall be drawn which exactly fits the view, the view is not defined
by the center coordinates and the range but by the corner coordinates. In that case the
geographic coordinates have to be transformed into cartesian coordinates and then into the
view port coordinates. Instead of EcDrawSetViewport the function EcDrawSetTransformation
has to be used.
The following sample code will draw a world overview in cylindric projection.
EcDrawSetProjection(view, EC_GEO_PROJECTION_CYLINDRIC, 0, 0, 0, 0);
double N1, N2, E1, E2;
EcDrawLatLonToCartesian(view, 80, -179.99, &N1, &E1);
EcDrawLatLonToCartesian(view, -80, 179.99, &N2, &E2);
EcTransformationMatrix M;
M.m11 = double(width) / (E2 - E1);
M.m21 = 0;
M.m31 = -M.m11 * E1;
M.m12 = 0;
M.m22 = double(height) / (N2 - N1);
M.m32 = -M.m22 * N1;
EcDrawSetTransformation(view, &M);

Since S-57 data are not seamless the functionality very much depends on the chart
extensions. Therefore we cannot guarantee that it will work with other charts than the

259
EC2007 ECDIS Kernel Programming Guide

SevenCs world datasets. Please also note that it only works with the 0° Meridian as center
longitude.

12.10 Localization
The localization of a chart display software is usually related to following parts:
• Graphical User Interface
• Display of chart text
• Display of chart pick report
The first is fully in charge of the application builder. For the other two parts the EC2007
ECDIS Kernel provides the necessary functions or files.

12.10.1 Display of Chart Text

According to S-52 the names of objects have to be displayed in English. Therefore all names
must be encoded with the attribute “Object Name” (OBJNAM). In case of national names in
local language the names have to be transliterated. If the original national name shall be
encoded as well, it has to be stored in the attribute “National object name” (NOBJNM).
However this attribute will not be used for the display but only OBJNAM, i.e. only English or
transliterated names will be displayed.
The symbols and the display of names of objects are managed in the lookup tables. In order
to change the official display of object names the lookup tables have to be exchanged.

Please Note
- With the use of these lookup tables the chart display of your application is not in
accordance with the IMO specifications and the IHO Standards.
- The maintenance of these lookup tables is not covered by any support contract.
- The lookup tables are only available for the display of ENCs.

In case the standard system font does not support the display of the required characters it
might be necessary to define the font the chart display explicitly with the function
EcDrawSetUnicodeFont. Depending on the font it might also be necessary to change the font
size with EcDrawSetTextSizeFactor.
An example of the lookup table handling can be found in the sample program showENC.

12.10.2 Display of Pick Report

Usually the pick report displays a list of all objects which are located at the pick position.
Listed are the object name, e.g. “Buoy lateral” with its attributes, e.g. “Colour: white,red”. To
display this information not in English but in another language, the EC2007 ECDIS Kernel
provides translation functions. The functions use translation tables which can be created by

260
 EC2007 ECDIS Kernel Programming Guide

the application builder. Chinese translation tables are included in the EC2007 ECDIS Kernel
package.
Following functions can be used for the translation:
• EcDictionaryCreateTranslationTable
• EcDictionaryFreeTranslationTable
• EcDictionaryTranslateLanguageObjectToken
• EcDictionaryTranslateLanguageAttributeToken
• EcDictionaryTranslateLanguageAttributeValue
An example of the use of the translation functions can be found in the sample program
showENC.

12.11 Dynamic Overlay Drawings

For applications which have to display not only charts but also a huge amount of fast moving
objects, e.g. AIS or ARPA targets, the EC2007 ECDIS Kernel provides a set of functions to
support such chart overlay features. Supported drawing sources are presentation library
symbols, icons, and bitmaps on Windows platforms and symbols, pixmaps, and images on
Unix platforms. Any drawable (bitmap/pixmap or window) can be used as the drawing
destination. The functions are optimized for the display of fast moving objects like targets
and user-defined symbols to be placed by "drag and drop". Presentation library symbols can
even be rotated. The term "dynamic object", as used in the function reference, describes a
handle to an overlay drawing resource created by the function EcDynamicObjectCreate. All
these handles are allocated in memory as a linked list with the anchor being stored in the
EcView structure passed to the functions. The internal stacking order of these "dynamic
objects" is defined by the order in which they have been created. An object will save the
background (i.e. the part of the drawing destination that will be completely or partly covered
by the object) before it is drawn, and will restore the background when it is moved or
deleted. All other objects in the linked list will automatically save and restore their
backgrounds if necessary.
Following is the list of functions that handle dynamic objects:
EcDrawNTDynamicObjectCreate creates a dynamic object on top of previous objects.
EcDrawNTDynamicObjectReplace replaces the object's drawing source keeping the
drawing order.
EcDrawDynamicObjectDeleteAll deletes all dynamic objects.
EcDrawNTDynamicObjectDelete deletes a specific dynamic object.
EcDrawNTDynamicObjectDraw draws a specific dynamic object.
EcDrawNTDynamicObjectDrawAll draws all dynamic objects.
EcDrawDynamicObjectGetFirst retrieves the first object of the linked list of dynamic
objects.
EcDrawDynamicObjectGetNext retrieves the next object of the linked list of dynamic

261
EC2007 ECDIS Kernel Programming Guide

objects.
EcDrawNTDynamicObjectGetInfo retrieves information about a specific dynamic
object.
EcDrawDynamicObjectPick retrieves all dynamic objects at a specified location.

12.12 Drawing Functions

In some cases it might be necessary to simply draw symbols, lines ore areas on the chart
display. This can be done either by functions of the GUI toolkit but also with Kernel
functions.

12.12.1 Drawing Symbols

The function EcDrawNTDrawSymbol can be used to draw one of the symbols of the
presentation library which are also used for the chart display. Vector symbols are located in
the directory $LIB_7CS\lil\preslib4\sym, raster symbols of different sizes in the sub-directories
ral (low resolution), ram (medium) and rah (high).

12.12.2 Drawing Lines and Areas

The function EcDrawNTDrawLine can be used for generic line drawings. Either type, color, and
width for simple lines or a line-stlye definition for complex lines can be specified. The
keywords used for the line type and color must match the specifications of the Presentation
Library.
The function EcDrawNTDrawArea can be used for generic area drawings. Either fill color and
transparency for color fills or a pattern definition for pattern fills can be specified. The
keywords used for pattern definition and color must match the specifications of the
Presentation Library.
Examples:
Dashed line, 2 pixels wide, in magenta:
int cx[2], cy[2];
cx[0]=100; cy[0]=100;
cx[1]=200; cy[1]=200;
EcDrawNTDrawLine(view, dc, NULL, "DASH", "CHMGD", 2, cx, cy, 2);

Complex line-style with anchors

int cx[2], cy[2];
cx[0]=100; cy[0]=100;
cx[1]=200; cy[1]=200;
EcDrawNTDrawLine(view, dc, NULL, "ACHARE51", "", 0, cx, cy, 2);

Opaque-filled area in magenta:

262
 EC2007 ECDIS Kernel Programming Guide

int cx[4], cy[4];

cx[0]=100; cy[0]=100;
cx[1]=200; cy[1]=200;
cx[2]=100; cy[2]=200;
cx[3]=100; cy[3]=100;
EcDrawNTDrawArea(view, dc, NULL, "CHMGD", False, False, cx, cy, 4);

Area filled with a air plain pattern:

int cx[4], cy[4];
cx[0]=100; cy[0]=100;
cx[1]=200; cy[1]=200;
cx[2]=100; cy[2]=200; cx[3]=100; cy[3]=100;
EcDrawNTDrawArea(view, dc, NULL, "AIRARE02", False, False, cx, cy, 4);

12.13 Display Functions

EcChartAddDisplayFunction can be used to install a display function. Display functions are
similar to conditional symbology procedures, but unlike those procedures they are called
during the chart drawing process, not during symbolization.
After a display function has been installed the Kernel will recognize the new symbol
instruction DF(function). In case such a symbol instruction is parsed, either from a lookup
table entry or from a conditional symbology procedure, the name of the function will be
stored in the display list. Whenever the display list is processed by one of the chart drawing
functions the installed display function will be called for each object that has a
corresponding DF symbol instruction.
Display functions can be useful in case the presentation of an object depends on the current
drawing scale. Conditional symbology procedures cannot handle such an interdepedence
since they have no information about the scale.
In order to uninstall a display function you can use the function
EcChartRemoveDisplayFunction. Once it has been uninstalled the display function will no
longer be called.

12.14 Tidal Predictions

The EC2007 ECDIS Kernel offers a database with about 500 places where tidal predictions are
available. The database consists of a SENC file with the name 7C0TIDES.7CB and is located in
the directory $EC2007DIR/data/tides. The tide locations are encoded as “Tide - harmonic
prediction” (T_HMON). A list of all tide locations can be generated with the functions for the
cell data access (see chapter 11.3).

263
EC2007 ECDIS Kernel Programming Guide

Please note:
The Tide cell must NOT be loaded and drawn together with other general chart data, i.e.
it must not be imported into a DENC structure but loaded and mapped explicitly from
another directory.

The functions for tidal predictions extract the necessary parameters from the tide cell and
calculate the tide predictions for the defined location and time.
The example program and source code tidaltest demonstrates the use the tidal prediction
functions.

264
 EC2007 ECDIS Kernel Programming Guide

13 Miscellaneous
13.1 Rendering Performance
The performance of the chart rendering depends on:
• Hardware (please refer to EC2007_InstallationGuide.pdf)
• Number of charts, content of chart and display scale
• Use of multi-threading
• Caching of lookup table entries
• Use of processor intensive functions

13.1.1 Multi-threading
The EC2007 ECDIS Kernel uses a thread pool for internal workload expensive symbolization
functions. With the function EcKernelSetNumThreads the number of threads can be defined.
The default is not to use multi-threading, i.e. the number of threads is 0 and everything is
performed in the main thread. Setting the number of threads to 1 will shift symbolization
functions to one additional thread. In the available resources are already at the limit the use
of multi-threading might be harmful due to the overload of the thread administration.

Please note:
In case of single core processors it is advised not to enable the support of multi-threading
in the EC2007 ECDIS Kernel, i.e. not to use the function EcKernelSetNumThreads.
In case of multi-core processors the number of threads should not exceed two times the
number of cores.

13.1.2 Caching of lookup table entries.

During the symbolization process the EC2007 ECDIS Kernel parses the S-52 lookup tables for
each object in the charts. With the function EcChartSetLookupEntryCache a cache can be
enabled, i.e. the lookup entry that matches a certain attribute / value combination is
memorized. Especially with many features carrying the same attribute combinations this
cache can improve symbolization speed dramatically since expressions don't have to be
evaluated for each lookup table entry again. If there are a lot of different attribute / value
combinations, the cache may consume too much memory.

Please note:
The functions for caching lookup table entries should not be used together with the
multithreading support.

With the function EcChartClearLookupEntryCache the cache can be cleared. This might be
necessary in the case you are facing problems with too little memory.

265
EC2007 ECDIS Kernel Programming Guide

13.1.3 Processor Intensive Functions

There are many functions which are required by IEC 61174 and IEC 62288 and which
significantly influence the S-63 chart import and display performance.
The S-63 chart import issue has been recognized by the Hydrographic Community and more
and more HOs allow the distribution of their ENCs in SENC format, which improves the chart
import performance a lot.
The display requirements for ECDIS applications are mandatory for ECDIS applications only.
That means that for non-ECDIS applications they are not necessarily required. Therefore the
EC2007 ECDIS Kernel provides functions to disable the display of certain objects or
information.

[Link] Official Chart Boundary Calculation

With the function EcChartSetShowOfficalBoundary the display of the boundaries between
official and non-official data can be enabled and disabled. The default is to not show the
boundaries.

[Link] Shallow Water Dangers

Many charts contain areas with a high density of single underwater hazards, especially
underwater rocks. Very often they are located in shallow waters, i.e. an area which is too
shallow for the respective vessel as defined by the safety contour (see chapter [Link]).
Because such area is not navigable there is no real need to display all single underwater
hazards. That is why the display of such underwater hazards can be enabled and disabled
with EcChartSetShowShallowWaterDangers. The default is to not show these underwater
hazards.

[Link] Overscale Pattern

In ECDIS applications it has to be indicated whenever the display scale exceeds the
compilation scale. In that case the overscale pattern, i.e. perpendicular lines, have to be
drawn on the chart. This can be disabled with the function EcChartSetShowOverScale. The
default is to show the overscale pattern.

[Link] Depth Contour Labels

With the function EcChartSetShowDepthContourLabels the display of depth contour labels can
be switched on or off. The default is to not show the depth contour labels.

13.2 Chart Display Clutter – SCAMIN

The appearance of the chart images very much depend on the correct coding of the charts.
S-57 provides a so-called SCAMIN attribute which defines at which scale an object shall be
displayed during zooming in or suppressed during zooming out. Since the use of the
attribute SCAMIN is not mandatory for the chart producer there might be charts which have
no SCAMIN or no proper SCAMIN values.
The following two pictures show the chart display with SCAMIN and without SCAMIN.

266
 EC2007 ECDIS Kernel Programming Guide

Not using SCAMIN does not only impair the display of the chart but also the performance of
the chart display.
In case chart objects have no SCAMIN the function EcChartSetUseAutoScamin can be used to
assign SCAMIN during the symbolization.

Please note:
The function EcChartSetUseAutoScamin must not be used for ECDIS

13.3 Server/Client Applications

There are many applications which operate in a server/client environment. This applies
mainly to onshore applications, e.g. VTS, or to military onboard applications, e.g. a combat
management system. In all these cases usually a central chart management system is used,
i.e. all charts are imported and maintained centrally on a server.

13.3.1 Chart Maintenance

Chart maintenance, i.e. the chart import including decryption and authorization is carried
out centrally on a server. This means that the DENC structure containing the up-to-date
chart database is kept on the server. Although the clients could access the DENC structure
on the Server remotely this approach is not advisable for performance reasons. The chart
loading process (see chapter 6.6.4) is for the most part influenced by the input/output (I/O)
of the data storage medium. If the I/O processes are done via Local Area Network (LAN), the
performance of the chart loading process will be significantly increased. Instead SevenCs
recommends that each client has its own DENC structure, which is then synchronized with
the DENC structure on the server, either permanently or on demand.
After directENC packages or S-63 Exchange Sets have been imported onto the server all
SENC files within the DENC structure on the server are locally protected. The local protection

267
EC2007 ECDIS Kernel Programming Guide

depends on the SevenCs hardware ID, the source of which is defined in the server
application (see chapter 6.2). When clients read SENC charts which have been generated on
the server they have to use the same hardware ID as the server. In that case the use of the
Rockey network dongle is advisable since that dongle provides the same hardware ID to the
server and the clients (see chapter 6.2 and Installation Guide).

13.3.2 ENC Licensing

ENC licensing is totally independent of the softare registration by means of the SevenCs
hardware ID. According to the S-63 Standard the application builder has to guarantee that
each system is unique. It is up to the application builder to define the number of applications
within a system which share the same S-63 User Permit. At the end it is fully in the
responsibility of the end user of the applications to have the required number of licenses for
each system.
Most Hydrogrpahic Offices allow sharing ENCs on up to five applications within a physical
environment, i.e. one vessel or one VTS. However it is not feasible for systems with more
than five installations to have different S-63 User Permits for each five installations.
Therefore chart providers like ChartWorld Int. [Link] offer the possibility to
have the chart license issue treated on a mere contractual basis.

268
 EC2007 ECDIS Kernel Programming Guide

14 Additional Tools
14.1 WMS Library
Nowadays there are more and more applications where it is necessary to display standard
electronic nautical charts in combination with, or as a backdrop to, other geospatial data.
Many of these applications are running as a server/client solution, i.e. the server generates
the chart image and provides it to the clients. For this purpose the Open Geospatial
Consortium (OGC) has developed the Web Map Service (WMS) protocol.
The EC2007 ECDIS Kernel provides the additional WMS library which can be used to simplify
building a WMS compatible server or client. Thus it is not necessary to learn all details about
the WMS protocol and to establish relations to the functions of the EC2007 Kernel. The WMS
module assists with generating appropriate WMS responses in XML format (i.e. server
capabilities and error codes) which can be sent (more or less) directly to a WMS client or a
drawn image.
The WMS libraray does not contain encoding/decoding functionalities for different image
formats. Furthermore it does not contain an XML parser to deal with XML responses
received from a remote WMS server.
In this document it is assumed that the reader has basic knowledge of HTTP communication,
XML and image manipulation.
The current version of the WMS library supports WMS versions 1.1.1 and 1.3.0.
The WMS protocol uses HTTP as carrier protocol. The HTTP GET requests are supplied with
the information required to build a response result. The implementation and technical
details of building an HTTP server and / or client is beyond the scope of the WMS library.

14.1.1 Components
The WMS module contains the following parts:
• Server functionality
- Serving Layer Manager
- URL Parser
- URL Processing Callbacks Framework
• Client functionality
- URL Generator
- Common client and server functionality
- Spatial Reference System (SRS) / Coordinate Reference System (CRS) to EC2007 datum
and
projections mapping
- Memory decallocation

269
EC2007 ECDIS Kernel Programming Guide

14.1.2 Server Functionality

The WMS library functions use an opaque WMS Context object to keep persistent data. This
needs to be initialized before use, passed on to the WMS library client or server functions
and freed when no longer needed. A Context object is thread safe and may be used to
process simultaneous calls. However, it should be noted that one EcView object is needed
for each thread when calling the URL Parser simultaneously from several threads.
Mapping from WMS CRS/SRS namespaces to EC2007 Kernel datums and projections is done
with mapping files. Format and syntax of these files are described in the provided sample
files. The EcWMSSrvInitialize function takes the path to search for mapping files (ending with
.WMS). If no path is provided (i.e. the path parameter is an empty string or NULL) the path
constructed with the environment variable CFG_7CS and the sub-directory wms (i.e.
$CFG_7CS/wms/) will be [Link] WMS server also requires the URL to state in the
capabilities document, i.e. the publicly visible server address (for example
[Link]
The WMS library will, if configured correctly, prepare and draw an image into the provided
drawing context when parsing a URL. The application using the WMS library must, however,
specify the possible image formats as MIME types since the support for an image format is
highly depending on other libraries which may have licensing restrictions making the
redistribution of such libraries with the EC2007 WMS library problematic. The MIME type
registration may contain a callback function that does the actual pixel conversion. If so, the
URL parsing function will generate a full response for a GetMap request including HTTP
headers. If not, the application will have to do the conversion from drawing context to image
and produce the necessary header information.
A note on WMS versions: per default the versions 1.0.x, 1.1.x and 1.3.x (only the major and
minor version numbers are verified) are supported. The function EcWMSSrvSetVersion can be
used to restrict the supported WMS version to the exact string given as parameter. This
version will also be stated in the capabilities document. The default behavior if no version is
explicitly set is to report the version requested in the URL (i.e. the value of the VERSION
parameter), if present. If no specific version is requested the version 1.3.0 will be used. The
custom version can be unset using a call with a version string set to NULL or an empty string
(“”).

[Link] Serving Layer Manager

The WMS request model is based on requesting one or more layers, i.e. data subsets or
types of data, with one style per layer. Layers are to be drawn on top of each other in the
requested sequence. As a side note, WMS also offers the optional possibility of the client
sending a style definition to the server, so called Styled Layer Descriptor (SLD) WMS. This
functionality is not part of the EC2007 WMS module.
The Serving Layer Manager allows defining a number of different layers, each with a number
of different styles. If no layers are explicitly defined the layer manger will provide the default
layer SENC with the style default. If one or more layers have been defined the default layer
will no longer be used.
A GetFeatureInfo callback can be installed for a layer, marking it as queryable in the
capabilities document (see below).

270
 EC2007 ECDIS Kernel Programming Guide

[Link] URL Parser

The URL Parser processes a URL request and sets up the necessary view parameters.
A typical request as typed in a web browser looks like:
[Link]
ION=1.1.1&REQUEST=GetMap&SRS=EPSG:4326&SERVICE=WMS&FORMAT=imag
e/png&BBOX=-69.858933,-71.872579,-66.703718,-
71.076655&WIDTH=1280&HEIGHT=1024&STYLES=
The same request when received over HTTP looks like:
GET_/[Link]?LAYERS=test&TRANSPARENT=TRUE&VERSION=1.1.1&REQUES
T=GetMap&SRS=EPSG:4326&SERVICE=WMS&FORMAT=image/png&BBOX=-
69.858933,-71.872579,-66.703718,-
71.076655&WIDTH=1280&HEIGHT=1024&STYLES=_HTTP/1.0
The parameter string must conform to RFC2396. Any extra processing and character
(de)escaping according to RFC2396 is assumed to be done outside the WMS module.
The URL parser processes the following part of the string:
LAYERS=test&TRANSPARENT=TRUE&VERSION=1.1.1&REQUEST=GetMap&SRS=
EPSG:4326&SERVICE=WMS&FORMAT=image/png&BBOX=-69.858933,-
71.872579,-66.703718,-71.076655&WIDTH=1280&HEIGHT=1024&STYLES=
Parameter names are case insensitive but parameter values are case sensitive, i.e.
REQUEST=GetMap is the same as request=GetMap but not as REQUEST=getmap.
Memory is internally allocated for the resulting document and MIME type which must be
freed by the application using EcWMSFree when no longer needed.

[Link] Workflow
1. If a URL preprocessing callback has been installed it is called.
2. The URL is clean and verified.
3. If the request is a GetCapabilities an XML capabilities document is generated and the
processing ends.
4. The EcView object viewport according is set up corresponding to the requested CRS/SRS
and bounding box using the CRS/SRS namespace mappings in the mapping files found in
the path passed to the initialization function.
5. A new pixmap for the drawing context corresponding to the width/height parameters of
the request is created. The new pixmap is cleared with the background color requested
in the URL (default color if the BGCOLOR parameter does not exist is white).
6. Each requested layer is processed in turn
6.1. The layer style callback is called to setup EcView object for drawing (i.e. setting
EcView parameters and loading cells). When a URL with an empty STYLE
parameter is parsed the style name default will be used if defined. If no style
named default has been defined the first registered style callback will be called. If
no callbacks are defined for a layer parsing a URL with no styles or default as
requested style will correspond to calling the functions EcChartUnloadView

271
EC2007 ECDIS Kernel Programming Guide

followed by EcChartLoadViewByArea.
6.2. If the request is a GetMap the main callback of the layer is called to draw the chart
into the drawing context. If no layer callback is has been defined the default
behaviour is calling the function EcChartSymbolizeView followed by
EcDrawNTDrawView. If no layers are defined the layer name SENC will be accepted
and rendered using the previously stated functions.
6.3. If the request is a GetFeatureInfo plus the layer has a feature info callback
installed and the layer is in the list of layers to query the feature info callback is
called. The callback must then generate the appropriate return document. Format
and information of the response to a GetFeatureInfo request has not been
defined by the WMS specification. Thus there is no default behavior if no callback
has been installed, and the appropriate WMS exception document is generated
and the processing ends.
7. If a URL postprocessing callback is installed it is called.
8. If the request is a GetMap
8.1. If a callback for the requested MIME type has been registered it is called and the
processing ends.
8.2. If a callback for the requested MIME type has not been registered an appropriate
WMS exception document is created, and the processing ends (in this case the
application may generate an image from the drawing context and ignore the WMS
exception document returned by the URL parser).
9. If the request is a GetCapabilities a capabilities XML document is generated and the
processing ends.

[Link] URL Callback Framework

Callbacks can be registered for layers, layer styles, URL preprocessing, URL postprocessing,
GetFeatureInfo queries and MIME type image conversion. The callbacks enable the
application to modify the behaviour of the URL parser or, more precisely, the resulting
image. Each callback function has the following function prototype (replace func with the
name of the actual function):
Bool func( EcWMSContext *cT, caddr_t userData ).
The cT parameter can be used to retrieve and set parameters for the current parsing session.
If custom data is set using EcWMSSrvSetCustomData the data will be copied and returned by
the URL parser in response to the query (must be used to return a result to a GetFeatureInfo
request, or to set the formatted image data to a GetMap request).

[Link] XML Exception Generation

The XML Exception Generator converts an error code into the required XML WMS exception
format. The function EcWMSGetException allocates the memory required to hold the result
which must be freed using EcWMSFree when no longer needed.

272
 EC2007 ECDIS Kernel Programming Guide

The version stated in the exception document adds the EcWMSSetSrvVersion function to the
version. If no custom version has been set the default behaviour is to use the version of the
last request parsed by the URL Parser by the current thread. If no URL has been parsed the
version 1.3.0 is used.
The exception generator is used internally by the URL parser, but may also be called
separately.

[Link] XML Capabilities Generator

The XML Capabilities Generator converts the configured server layers into the required XML
WMS capabilities format. The function EcWMSGetCapabilities allocates the memory required
to hold the result which must be freed using EcWMSFree when no longer needed.
The capabilities generator is used internally by the URL parser but may also be called
separately.

14.1.3 Client Functionality

The WMS module functions use an opaque WMS Context object to keep persistent data.
This needs to be initialized before use, passed on to the WMS module client or server
functions and freed when no longer needed. A WMS Context is thread safe and may be used
to process simultaneous calls. The initialization needs the path where to find the file(s) for
the SRS/CRS mappings (see previous chapter 14.1.2)
The WMS module needs to know which version to use when generating requests. This must
be set with EcWMSClientSetVersion before request URLs can be generated. The SRS/CRS used
in a request is generated from the settings of the EcView object passed to the generator
function. It is recommended that the application implementing a WMS client first retrieves
the capabilities of the remote server to find out which layers are available and which
SRS/CRS are supported. The desired SRS/CRS can then be used to prepare an EcView to be
able to draw a retrieved image from the remote server.
The EC2007 Kernel WMS module does not provide a facility for parsing XML files. It is
recommended that the application implementing a WMS client also uses a suitable library to
process the WMS XML responses.

[Link] URL Generator

The EcWMSClientGet* functions can be used to generate URLs suitable for requesting
information from a remote WMS server. Always required is the base URL, i.e. the server
name and target path (for example [Link] ).
An example URL generated by the EcWMSClientGetCapabilites function would look like
[Link]
=GetCapabilities
The application may at its discretion post process the generated URL to remove, modify or
add any extra parameters. Memory is allocated for the generated URLs which must be freed
using EcWMSFree when no longer needed.

273
EC2007 ECDIS Kernel Programming Guide

14.1.4 Common Functionality

The WMS specification does not explicitly define any SRS/CRSs apart from those in the AUTO
and AUTO2 namespaces. The WMS specifications up to version 1.1.1 rely mainly on the EPSG
database of projections and datum definitions. The mapping files offer an application using
the WMS module to define namespaces and SRS/CRS codes at its own discretion. Samples
are provided with mapping files for the AUTO, AUTO2 and CRS namespaces as well as an
excerpt from the EPSG namespace.
Note that all SRS/CRSs defined in the found mapping files will be offered to the client. The
AUTO namespace additionally relies on providing an EPSG scaling factor from which a subset
is implemented in the WMS module:

Value Unit Conversion

9001 metre
9002 foot 0,3048 meters
9003 us foot 0,304800609601219 meters
9014 fathom 1,8288 meters
9030 nautical mile 1852 meters
9035 us mile 1609,34721869444 meters
9036 km 1000 metres
9040 british yard 0,914398414616029 meters
9041 british foot 0,304799471538676 meters
9093 statute mile 1609,344 meters
9096 international yard 0,9144 meters
9101 radian
9102 degrees 0,0174532925199433 radians (PI/180)
9103 arc-minute 1/60 degrees
9104 arc-second 1/60 arc-minutes
9105 grad 0,015707963267949 radians (PI/200)
9112 centesimal minute 1/100 grad
9113 centesimal second 1/100 centesimal minutes

It is also worth noticing that most publicly available WMS servers implement WMS version
1.1.1 and support the EPSG:4326 SRS/CRS, but little more. The EPSG:4326 SRS/CRS is
basically a linear interpolation of latitude/longitude without projection which is suitable for
displaying e.g. satellite imagery.
Following SRS are supported by the WMS library:
AUTO:42001 Universal Transverse Mercator

274
 EC2007 ECDIS Kernel Programming Guide

AUTO:42002 Transverse Mercator

AUTO:42003 Orthographic
AUTO:42004 Equirectangular
EPSG: 3857 Pseudo Mercator
EPSG: 4326 WGS 84
EPSG:23028 ED50 / UTM zone 28N
| |
EPSG: 23038
ED50 / UTM zone 38N
EPSG:32601 WGS 84 / UTM zone 1N
| |
EPSG:32660
WGS 84 / UTM zone 60N
EPSG:32661 WGS84 / UPS North
EPSG:32701 WGS 84 / UTM zone 1S
| |
EPSG:32760
WGS 84 / UTM zone 60S
EPSG:32761 WGS84 / UPS South

The public functions of the projection mapper are used internally by the WMS module but
can also be used separately. Note that the function EcWMSDatumAndProjectionToCRS
allocates memory for the CRS string which must be de-allocated with EcWMSFree when no
longer needed.

14.2 3D Library
The SevenCs 3D-Module provides a library for the three-dimensional presentation of S-57
ENC data, DTED and BAG data. In conjunction with the EC2007 ECDIS Kernel the library can
be used for creating and manipulating a three-dimensional scene that spatially visualizes
nautical information assigned to the 3D-Module.
The 3D-Module is based on OpenGL and the scene graph system OpenSG (Version 1.8.0).
For a detailed programming guide please refer to the document EC2007_3DLib.
An example implementation of the 3D functions can be found in the example program
3dtestosg.

275
EC2007 ECDIS Kernel Programming Guide

15 Release Notes
These release notes describe the latest new features, changes and bug fixes implemented
since version 5.18.2 of January 2015.

15.1 Version 5.20.0

The release of the EC2007 ECDIS and SharpCoat Kernel was mainly driven by the new
editions of the:
• IEC 61174 Standard, i.e. edition 4.0
• IHO S-52 Presentation Library, i.e. edition 4.0
• IHO S-64 Test Standard, i.e. edition 3.0
In addition the new ChartHandler is provided with EC2007 ECDIS and SharpCoat Kernel.

15.1.1 Standard Compliance

Following new functions and features are based on the new or revised requirements in the
standards mentioned above.

[Link] Detection and indication of navigation related objects

Following groups of navigation related objects have been introduced:
• Navigational hazards
• Areas for which special conditions exists
• Safety contour related dangers
For that reasons new danger dictionaries and the new function
EcDraw[NT][X11]HighlightDangers have been introduced in the EC2007 ECDIS Kernel.
Please refer to chapter 7.3.1 for details.

[Link] Viewing group layers and display selectors

The settings for the configuration of the chart display have been revised. In addition to the
existing S-52 display categories new viewing group layers and so-called display selectors
have been introduced.
Viewing group layers have still to be defined with the existing function
EcChartSetViewingGroup. The list of viewing groups is given in chapter 7.1.4.
For the S-52 display selectors there is a new function EcChartSetDisplaySelector.
Please refer to chapter 7.1.2 for details.

[Link] Pick report

Only those chart objects which are part of the selected display category or viewing group
layer shall be listed in the pick report. Therefore a new filter function EcQueryFilterFeatures
has been introduced.
Please refer to chapter 12.3 for details.

276
 EC2007 ECDIS Kernel Programming Guide

[Link] Display of date dependent objects

ENCs may contain objects which have attributes to define a certain date when the object will
be available or removed or certain periods in which the objects are available.
To indicate those objects and apply the dates to the chart display the function
EcChartSetDisplaySelector has to be used.
Please refer to chapter 7.1.5 for details
For manual updates the new function EcChartSetManualUpdateDateRange has to be used.

[Link] Indication of overlapping cells

To indicate the existence of overlapping cells in the view a new function
EcDrawCheckCellOverlap has been introduced.

[Link] Indication of automated updates

To indicate automated chart updates the new function
EcDraw[NT][X11]HighlightUpdateHistory has been introduced.
To create the necessary SENC update history files the function EcS57V3SetUpdateHistoryMode
or the new ChartHandler have to be used.
Please refer to chapter 7.4 for details.

[Link] S-52 Ed.4 / EC2007 ECDIS Kernel cross-reference

New ECDIS requirements

Clause Description EC2007 Function / Chapter
[Link] Ability to turn Isolated Dangers in EcChartSetDisplaySelector
Shallow Water on/off. [Link]
(see chapter 7.1.2)
10.4.2 Ability to turn SCAMIN on/off. EcChartSetDisplaySelector
[Link]
(see chapter 7.1.2)
10.5.7 Mandatory implementation of ability to EcChartSetDisplaySelector
display shallow water pattern. [Link]
(see chapter 7.1.2)
10.5.9 Detection and Notification of EcQueryReadDangerDictionary
Navigational Hazard. Lists the S-57 EcDraw[NT][X11]HighlightDangers
features and attributes that will raise an
indication. (see chapter 7.3)

10.5.9 New Mariner Object ‘indhlt’ n/a

10.5.10 Detection of Areas, for which Special EcQueryReadDangerDictionary
Conditions Exist. Lists the S-57 features EcDraw[NT][X11]HighlightDangers
and attributes that will raise an
indication or alert as defined by the (see chapter 7.3)

277
EC2007 ECDIS Kernel Programming Guide

Mariner.
10.5.12 Detecting the Safety Contour. Lists the S- EcQueryReadDangerDictionary
57 feature and attribute combinations EcDraw[NT][X11]HighlightDangers
required to detect the safety contour.
(see chapter 7.3)
Rocks, Wrecks and Obstructions have
been removed in e4.0.0 from detection
of the safety contour process and moved
to Detection and Notification of
Navigational Hazards. This change is in
line with the IMO PS requirement
[Link] New viewing group created to allow EcChartSetDisplaySelector
separate display on/off for INFORM01 ds. bShowInformPoints
symbol: “Highlight info” for INFORM and
NINFOM. “Highlight document” for ds. bShowExtFiles
TXTDSC, NTXDSC and PICREP. (see chapter 7.1.2)
10.7.2 Use of new symbols for identifying EcS57V3SetUpdateHistoryMode
automatic ENC updates. EcDraw[NT][X11]HighlightUpdateHistory
(see chapter 7.4)
14.3 Adoption of the IMO PS naming EcChartSetViewingGroup
convention for ECDIS viewing groups (see chapter 7.1.4)
available in ECDIS.

Changes and Clarifications

Clause Description EC2007 Function / Chapter
10.1.3 ECDIS must only display one ENC chart EcDrawCheckCellOverlap
in an area where ENC cells of the same
scale and usage overlap.
10.4 A means to insert a date or date range EcChartSetDisplaySelector
to display date dependant features. [Link]
New symbol to indicate where in the [Link]
chart display the objects with temporal
attributes are located. (see chapter 7.1.2)

[Link] Test Frame – S-64

The EC2007 ECDIS Kernel is provided with a test frame which includes all tests of chapter
3,5,6,7 of the S-64 standard Ed. 3. For details please refer to the manual of the Test Frame.

15.1.2 Bug Fixes

• Text positioning in horseshoe formed areas
• Color of depth numbers in underwater hazards
• ARCS drawing (Linux only)

278
 EC2007 ECDIS Kernel Programming Guide

15.1.3 Registration
In most case the hard disk recognition on newer Linux distributions, i.e. Red Hat 6 and
openSUSE 12, did not work and the EC2007 ECDIS Kernel had to be registered on the
network card or dongle.
Therefore the hard disk recognition had been revised. In case the hard disk recognition
worked with older versions of the EC2007 ECDSI Kernel and the new one calculates a
different hardware ID, the old method can be enabled again by setting the environment
variable EC_CHKDSK_SCSI has to be defined with any value.

15.1.4 Development Environment

[Link] New supported platforms

EC2007 and SharpCoat are now available for:
• Windows, Visual Studio 2013, 32 and 64 bit
• Red Hat / CentOS 7, 64 bit
• openSUSE 13, 64 bit

[Link] Linking of Linux system libraries

The openSSL and the boost libraries are now linked dynamically with the version of the
respective Linux distribution.
This does not apply to Red Hat 5, openSUSE 11 and SUSE Enterprise 10.

279
EC2007 ECDIS Kernel Programming Guide

15.2 Version 5.18.2

Chart Drawing
• Support of new AML 3 presentation library
• Improved drawing of centered symbols in case of u- and o-shaped areas.

ARCS
• CRC check during ARCS installation

S-63 Handling
• Graphical indication of ENCs with expired chart permits

Danger Highlight (IEC 62288, Ed 2)

• Adjusted danger highlight to only the dangerous parts of objects and not the entire object

Bug Fixes
• SENC Permit updating (only applicable in case of the use of protected directENC)

15.3 Version 5.18.0

Development Envirornment / Operating System
• EC2007 and SharpCoat are now available for Visual Studio 2010, 32 and 64bit.

Use of 3rd Party Memory Management Tools

Due to increasing problems and decreasing performance gains on Windows 7 and 8, EC2007
and SharpCoat are not making use of the memory management tool SmartHeap anymore.
Investigations have shown that the performance gain on Windows 7 and 8 is almost zero,
compared to Windows XP.

Software Registration
• The recognition of network cards was revised. The recognition does not depend anymore
on the number of network devices, device names, system locale or device status

Please note:
In case of more than one plugged network device it might happen that the new
registration does not provide the same MAC adress or hardware Id as an older
registration. Please contact support@[Link] in case this happens.

• Revision of dongle registration via remote login

• Updated Sentinel dongle libraries with fix of memory leak

Chart Products
• Digital Terrain Elevation Data (DTED) – Linux only
Note: A seperate library is provided
• ARINC 424 aviation charts (not supported on Red Hat 5 and OpenSUSE 11)

280
 EC2007 ECDIS Kernel Programming Guide

Chart Installation
• Faster SENC (directENC) Permit updating in case of huge permit files

Bug Fixes
• DENC import functions EcDENCImport* returned only EC_DENC_IMPORT_ERROR in case
charts were already installed. For new return values please refer to eckernel.h.
• Import of AIO data sets with world coverage
• Display of AIS speed and course vectors
• S-63 Decryption (Hash Comparison) on 64bit systems
• Display of sector lights which only have one sector leg defined
• Filerting object classes, i.e. EcChartFilterObjectClass and EcChartFilterObjectClassExt

Miscellaneous
• IENC 2.3 dictionaries in German language added
• Scale Minimum table for VPF based products added for the use of Auto Scamin

SharpCoat Only
• Improved and extended exception handling
• Revised chart handling for S-64 compliance

281
EC2007 ECDIS Kernel Programming Guide

16 Annex
A. EcNmea Data Structures
On the following pages all message types which are supported by the Kernel functions are
listed. The descriptions include the specification of the message type in the IEC 1162-1
standard, the corresponding data structure used to store the values, and the defines for the
bit mask combination of the data field available.

DBT - Depth Below Transducer

Water depth referenced to the transducer.

Water depth - in feet. Converted into meters and stored in field [Link]
1. Water depth - in meters. If no data in first field the value is stored in field [Link]
2. Water depth - in fathoms. If no data in the first two fields the value is converted into
meters and stored in field [Link]
The structure EcDBT_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
double depth; // depth (referenced to transducer) in meters
int talker; // code for the device type
}EcDBT_type;

The define for the bit mask combination of the data field available is as follows:
EC_DBT_DEPTH 1

DPT - Depth
IMO Ref. A224 (VII). Water depth relative to the transducer and offset of the measuring
transducer. Positive offset numbers provide the distance from the transducer to the
waterline. Negative offset numbers provide the distance from the transducer to the part of
the keel of interest.

1. Depth - in meters. Stored in field [Link]

2. Offset - in meters. “positive” = distance from transducer to water-line; “negative“ =
distance from transducer to keel. Stored in field [Link]
The structure EcDPT_type and all its data fields are listed below:

282
 EC2007 ECDIS Kernel Programming Guide

typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
double depth; // depth (referenced to transducer) in meters
double offset; // transducer offset in meters:
// + => to water-line, - => to keel
int talker; // code for the device type
}EcDPT_type;

The defines for the bit mask combination of the data field available are as follows:
EC_DPT_DEPTH 1
EC_DPT_OFFSET (1<<1)

DTM - Datum Reference

Local geodetic datum and datum offset from a reference datum. This sentence is used to
define the datum to which a position location, and geographic locations in subsequent
sentences, are referenced.

1. Three-character alpha code for local datum. W84 = WGS84, W72 = WGS72, S85 = SGS85,
P90 = PZ90, 999 = user-defined, IHO datum code (Stored in field [Link])
2. One character subdivision datum code when available or user-defined reference
character for user-defined datum, null field otherwise. Subdivision character from IHO
Publication S-60 Appendices B and C. Stored in field [Link].
The structure EcDTM_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec
// since 1.1.1970
char datumCode[4]; // 3 character datum code
char countryCode; // single character country code
int talker; // code for the device type
}EcDTM_type;

The defines for the bit mask combination of the data field available are as follows:
EC_DTM_DATUM_CODE 1
EC_DTM_COUNTRY_CODE (1<<1)

GGA - Global Positioning System Fix Data

Time, position, and fix related data for a GPS receiver.

283
EC2007 ECDIS Kernel Programming Guide

1. UTC of position. Stored in field [Link]

2. Latitude - N/S. Stored in field [Link]
3. Longitude - E/W. Stored in field [Link]
4. GPS quality indicator: 0 = fix not available or invalid, 1 = GPS fix, 2 = Differential GPS fix
(Stored in field [Link])
5. Number of satellites in use, 00-12, may be different from the number in view. Stored in
field [Link]
6. Horizontal dilution of precision. Stored in field [Link]
7. Antenna altitude above/below mean-sea-level (geoid) - in meters. Stored in field
[Link]
8. Geoidal Separation: the difference between the WGS-84 earth ellipsoid and mean-sea-
level (geoid), "-" = mean-sea-level below ellipsoid - in meters. Stored in field
[Link]
9. Age of Differential GPS data: Time in seconds since last SCl04 Type 1 or 9 update, null
field when dGPS is not used. Stored in field [Link]
10. Differential reference station ID, 0000-1023. Stored in field [Link]
The structure EcGGA_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
double latitude; // in degrees
double longitude; // in degrees
double altitude; // altitude of antenna
double horDilut; // horizontal dilution of prec.
double geoSep; // geoidal separation
double diffAge; // age of differential data
long timeOfPosition // milliseconds since midnight
int quality; // GPS quality indicator
int satInUse; // number of satellites in use
int refId; // reference station ID
int talker; // code for the device type
}EcGGA_type;

The defines for the bit mask combination of the data field available are as follows:
EC_GGA_FIXTIME 1
EC_GGA_LAT (1<<1)
EC_GGA_LON (1<<2)
EC_GGA_QUALITY (1<<3)
EC_GGA_USED_SATS (1<<4)
EC_GGA_HDOP (1<<5)

284
 EC2007 ECDIS Kernel Programming Guide

EC_GGA_ALTITUDE (1<<6)
EC_GGA_GEOSEP (1<<7)
EC_GGA_DIFF_AGE (1<<8)
EC_GGA_DIFF_REFID (1<<9)

GLL - Geographic Position - Latitude/Longitude

Latitude and Longitude of present vessel position, time of position fix, and status.

1. Latitude - N/S. Stored in field [Link]

2. Longitude - E/W. Stored in field [Link]
3. UTC of position. Stored in field [Link]
4. Status: A = Data valid. Stored in field [Link]
The structure EcGLL_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
double latitude; // in degrees
double longitude; // in degrees
long timeOfPosition // milliseconds since midnight
int valid; // indicates if received data is valid
int talker; // code for the device type
double version; // version of GLL (1.5 or 2.0)
}EcGLL_type;

The defines for the bit mask combination of the data field available are as follows:
EC_GLL_LAT 1
EC_GLL_LON (1<<1)
EC_GLL_TIME (1<<2)
EC_GLL_VALID (1<<3)

HDT - Heading - True

Actual vessel heading in degrees True produced by any device or system producing true
heading.

1. Heading in degrees - True. Stored in field [Link]

The structure EcHDT_type and all its data fields are listed below:
typedef struct
{

285
EC2007 ECDIS Kernel Programming Guide

int msgType; // message type

int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
double heading; // 0..360 degrees
int talker; // code for the device type
}EcHDT_type;

The define for the bit mask combination of the data field available is as follows:
EC_HDT_HEADING 1

HDG - Heading, Deviation, and Variation

Heading (magnetic sensor reading), which if corrected for deviation, will produce Magnetic
heading, which if offset by variation will provide True heading.

1. Magnetic sensor heading in degrees. Stored in field [Link]

2. Magnetic Deviation in degrees E/W. Add eastward deviation (E) to and subtract
westward deviation (W) from Magnetic Sensor Reading to obtain Magnetic Heading.
Will be null field if unknown. Stored in field [Link]
3. Magnetic Variation in degrees E/W. Add eastward variation (E) to and subtract
westward variation (W) from Magnetic Heading to obtain True Heading. Will be null
field if unknown. Stored in field [Link]
The structure EcHDG_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
double heading; // heading in degrees
double deviation; // deviation in degrees, negative = westwards
double variation; // variation in degrees, negative = westwards
int talker; // code for the device type
}EcHDG_type;

The define for the bit mask combination of the data field available is as follows:
EC_HDG_HEADING 1
EC_HDG_DEVIATION (1<<1)
EC_HDG_VARIATION (1<<2)

MWV - Wind Speed and Angle

When the Reference Field is set to Relative, data are provided giving the wind angle in
relation to the vessel's heading and wind speed, both relative to the (moving) vessel. When
the Reference Field is set to True, data is provided giving the wind angle relative to the
vessel's heading and wind speed, both with reference to the (moving) water. True wind is

286
 EC2007 ECDIS Kernel Programming Guide

the vector sum of the Relative (Apparent) wind vector and the vessels velocity vector along
the heading line of the vessel. It represents the wind at the vessel if it were stationary
relative to the water, and heading in the same direction.

1. Wind angle - 0 to 360 degrees. Stored in field [Link]

2. Reference - R = Relative, T = True (Stored in the field [Link])
3. Wind speed - units K/M/N. Converted into knots if necessary and stored in field
[Link]
4. Status - A = data valid (Stored in field [Link])
The structure EcMWV_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
double angle; // wind angle: 0..360 degrees
int reference; // angle is true or relative to ship
double speed; // wind speed in knots
int valid; // indicates if received data is valid
int talker; // code for the device type
}EcMWV_type;

The defines for the bit mask combination of the data field available are as follows:
EC_MWV_ANGLE 1
EC_MWV_ANGLE_REF (1<<1)
EC_MWV_SPEED (1<<2)
EC_MWV_VALID (1<<3)

OSD - Own Ship Data

Heading, course, speed, set and drift summary. Useful for, but not limited to RADAR/ARPA
applications.

1. Heading in degrees - True. Stored in field [Link]

2. Heading status - A = data valid. Stored in field [Link]
3. Vessel course in degrees - True. Stored in field [Link]
4. Course reference -B = Bottom tracking log, M = Manually entered, W = Water
referenced, R = RADAR tracking (of fixed target), P = Positioning system ground
reference (Stored in the field [Link])
5. Vessel speed. Converted into knots if necessary and stored in field [Link]

287
EC2007 ECDIS Kernel Programming Guide

6. Speed reference, see course reference for possible values. Stored in the field
[Link]
7. Vessel set in degrees - manually entered. Stored in the field [Link]
8. Vessel drift (speed). Converted into knots if necessary and stored in field [Link]
9. Speed units K/N/S. Not stored
The structure EcOSD_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
double heading; // true heading: 0..360 degrees
int headingStatus; // indicates if heading is valid
double course; // true course: 0..360 degrees
int courseRef; // indicates if course is valid
double speed; // speed in knots
int speedRef; // type of speed reference
double set; // set: 0..360 degrees
double drift; // drift in knots
int talker; // code for the device type
}EcOSD_type;

The defines for the bit mask combination of the data field available are as follows:
EC_OSD_HEADING 1
EC_OSD_HEADING_VALID (1<<1)
EC_OSD_COURSE (1<<2)
EC_OSD_COURSE_REF (1<<3)
EC_OSD_SPEED (1<<4)
EC_OSD_SPEED_REF (1<<5)
EC_OSD_SET (1<<6)
EC_OSD_DRIFT (1<<7)

RMC – Recommended Minimum Specific GNSS Data

Time, date, position, course, and speed data provided by a GNSS navigation receiver. This
sentence is transmitted at intervals not exceeding 2 seconds.

1. UTC of position fix. Stored in field [Link]

2. Status - V = Navigation receiver warning. Stored in field [Link]
3. Latitude - N/S. Stored in field [Link]
4. Longitude - E/W. Stored in field [Link]
5. Speed over ground in knots. Stored in field [Link]
6. Course over ground in degrees - True. Stored in field RMC. courseTrue

288
 EC2007 ECDIS Kernel Programming Guide

7. Date – dd|mm|yy. Stored in field [Link]

8. Magnetic variation - E = Eastward variation, subtracts from True course, W =
Westward variation, adds to True course (Stored in field [Link])
The structure EcRMC_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
int utc; // UTC of position fix in millisec after midnight
int status; // indicates if received data is valid
double latitude; // in degrees
double longitude; // in degrees
double speed; // speed in knots
double courseTrue; // true course: 0..360 degrees
int date; // date DDMMYY
double magVar; // magnetic variation in degrees
int talker; // code for the device type
}EcRMC_type;

The defines for the bit mask combination of the data field available are as follows:
EC_RMC_UTC 1
EC_RMC_STATUS (1<<1)
EC_RMC_LAT (1<<2)
EC_RMC_LON (1<<3)
EC_RMC_SOG (1<<4)
EC_RMC_CMG (1<<5)
EC_RMC_DATE (1<<6)
EC_RMC_MAGVAR (1<<7)

ROT - Rate Of Turn

Rate of turn, and direction of turn.

1. Rate of turn in degrees per minute, ‘-‘ = bow turns to port. Stored in field
ROT.rate_of_turn
2. Status - A = Data is valid. Stored in field [Link]
The structure EcROT_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
double rate_of_turn; // in degrees/minute
int valid; // indicates if received data is valid

289
EC2007 ECDIS Kernel Programming Guide

int talker; // code for the device type

}EcROT_type;

The defines for the bit mask combination of the data field available are as follows:
EC_ROT_TURNRATE 1
EC_ROT_VALID (1<<1)

RPM – Revolutions
Shaft or engine revolution rate, and propeller pitch.

1. Source, shaft(S)/engine(E)
2. Engine or shaft number, numbered from centerline, odd = starboard, even = port, 0 =
single or on centerline. Stored in field [Link]
3. Speed, revolutions per minute, ‘-‘ = counterclockwise. Stored in field [Link]
4. Propeller Pitch, percent of maximum, ‘-‘ = astern. Stored in field [Link]
5. Status - A = Data is valid. Stored in field [Link]
The structure EcRPM_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
int source; // data source (shaft/engine)
int number; // source ID
double rpm; // revolutions per minute
// (‘-‘ = counterclockwise)
double pitch; // propeller pitch in percent (‘-‘ = astern)
int valid; // indicates if received data is valid
int talker; // code for the device type
}EcRPM_type;

The defines for the bit mask combination of the data field available are as follows:
EC_RPM_SOURCE 1
EC_RPM_NUMBER (1<<1)
EC_RPM_RPM (1<<2)
EC_RPM_PITCH (1<<3)
EC_RPM_VALID (1<<4)

RSA - Rudder Sensor Angle

Relative rudder angle, from rudder angle sensor.

290
 EC2007 ECDIS Kernel Programming Guide

1. Starboard (or single) rudder sensor. Relative measurement of rudder angle without
units, ‘-‘ = ‘turn to port’. Sensor output is proportional to rudder angle but not
necessarily 1:1. Stored in field [Link]
2. Status - A = Data is valid. Stored in field [Link]
3. Port rudder sensor. Relative measurement of rudder angle without units, ‘-‘ = ‘turn to
port’. Sensor output is proportional to rudder angle but not necessarily 1:1. Stored in
field [Link]
4. Status - A = Data is valid. Stored in field [Link]
The structure EcRSA_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
double valueStb; // rudder angle sensor starboard (or single)
int stbValid; // indicates if received starboard value is valid
double valuePort; // rudder angle sensor port
int portValid; // indicates if received port value is valid
int talker; // code for the device type
}EcRSA_type;

The defines for the bit mask combination of the data field available are as follows:
EC_RSA_VALUESTB 1
EC_RSA_STB_VALID (1<<1)
EC_RSA_VALUEPORT (1<<2)
EC_RSA_PORT_VALID (1<<3)

SNU – Loran-C SNR Status

Loran-C warning flag for Signal-To-Noise-Ratio indicating that one or more Loran-C stations
being used to produce Lat/Lon and other navigation data are unreliable.

1. Warning flag. Stored in field [Link]

The structure EcSNU_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
int valid; // indicates if received data is valid
int talker; // code for the device type

291
EC2007 ECDIS Kernel Programming Guide

}EcSNU_type;

The defines for the bit mask combination of the data field available are as follows:
EC_SNU_VALID 1

TLL – Target Latitude and Longitude

The latitude and longitude of a target.

1. Target number, 00 to 99. Stored in field [Link]

2. Target Latitude - N/S. Stored in field [Link]
3. Target Longitude - E/W. Stored in field [Link]
4. User data – e.g. target name. Stored in field [Link][16]
5. UTC of data. Stored in field [Link]
6. Target status - L = Lost, tracked target has been lost. Q = Query, target in the process of
acquisition, T = Tracking (Stored in field [Link]. See also defines described below)
7. Reference Target = R, null otherwise. Stored in field [Link].
The structure EcTLL_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
int id; // target identifier
double latitude; // in degrees
double longitude; // in degrees
char userData[16]; // e.g. the target name
long timeOfPosition // milliseconds since midnight
int status; // indicates if target is Lost, Queried or tracked
int referenceFlag; // indicates if target is a reference target
int talker; // code for the device type
}EcTLL_type;

The defines for the bit mask combination of the data field available are as follows:
EC_TLL_ID 1
EC_TLL_LAT (1<<1)
EC_TLL_LON (1<<2)
EC_TLL_USERDATA (1<<3)
EC_TLL_TIME (1<<4)
EC_TLL_STATUS (1<<5)
EC_TLL_TARGET_REF_FLAG (1<<6)

292
 EC2007 ECDIS Kernel Programming Guide

TTM - Tracked Target Message

Data associated with a tracked target relative to own ship's position.

1. Target number, 00 to 99. Stored in field [Link]

2. Target distance from own ship. Stored in field [Link]
3. Bearing from own ship in degrees – true/relative (T/R). Stored in fields [Link] and
[Link]
4. Target speed. Stored in field [Link]
5. Target course in degrees – true/relative (T/R). Stored in fields [Link] and
[Link]
6. Distance of closest-point-of-approach. Stored in field [Link]
7. Time to closest-point-of-approach, ‘-‘ = increasing. Stored in field [Link]
8. User data – e.g. target name. Stored in field [Link][16]
9. Target status - L = Lost, tracked target has been lost. Q = Query, target in the process
of acquisition, T = Tracking (Stored in field [Link]. See also defines described below)
10. Reference Target = R, null otherwise. Stored in field [Link] (See also
defines described below)
11. UTC of data. Stored in field [Link]
12. Type of acquisition - A = Auto, M = Manual (Stored in field [Link]. See
also defines described below)
The structure EcTTM_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
int id; // target identifier
double distance; // distance in nautical miles
double bearing; // bearing: 0..360 degrees
int bearingmode; // flag to indicate if true or relative bearing
double speed; // speed in knots
double course; // course: 0..360 degrees
int coursemode; // flag to indicate if true or relative course
double CPAdist; // distance to CPA in nautical miles
double CPAtime; // time to CPA in minutes
char userData[16]; // e.g. the target name
int status; // indicates if target is Lost, Queried or
//Tracked
int referenceFlag; // indicates if target is a reference target
long time // milliseconds since midnight
int acquisitionType // indicates whether acquisition is done

293
EC2007 ECDIS Kernel Programming Guide

//manually or automatically
int talker; // code for the device type
}EcTTM_type;

The defines for the bit mask combination of the data field available are as follows:
EC_TTM_ID 1
EC_TTM_DISTANCE (1<<1)
EC_TTM_BEARING (1<<2)
EC_TTM_BEARING_TR (1<<3)
EC_TTM_TARGET_SPEED (1<<4)
EC_TTM_TARGET_COURSE (1<<5)
EC_TTM_TARGET_COURSE_TR (1<<6)
EC_TTM_CPA_DISTANCE (1<<7)
EC_TTM_CPA_TIME (1<<8)
EC_TTM_USERDATA (1<<9)
EC_TTM_TARGET_STATUS (1<<10)
EC_TTM_TARGET_REF_FLAG (1<<11)
EC_TTM_TIME (1<<12)
EC_TTM_TYPE (1<<13)

Additional defines used in this and the previous message (TTM and TLL) are:
EC_TARGET_LOST
EC_TARGET_QUERY
EC_TARGET_TRACKING
EC_TARGET_IS_NONREFERENCE
EC_TARGET_IS_REFERENCE
EC_ACQUISITIONTYPE_UNKNOWN
EC_ACQUISITIONTYPE_AUTOMATIC
EC_ACQUISITIONTYPE_MANUAL

Please note:
The old version of this message (NMEA Version 2.00) can also be parsed with the
function EcSensorReadNmea. The last two data fields UTC and acquisition type which
have been added in the new version of the message will then be treated as no-data
fields.

VBW - Dual Ground/Water Speed

Water referenced and ground referenced speed data.

1. Longitudinal water speed in knots, ‘-‘ = astern. Stored in field [Link]

2. Transverse water speed in knots, ‘-‘ = port. Stored in field [Link]

294
 EC2007 ECDIS Kernel Programming Guide

3. Status water speed – A = Data valid. Stored in field [Link]

4. Longitudinal ground speed in knots, ‘-‘ = astern. Stored in field
[Link]
5. Transverse ground speed in knots, ‘-‘ = port. Stored in field [Link]
6. Status ground speed – A = Data valid. Stored in field [Link]
The structure EcVBW_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
double waterSpeedL; // longitudinal water speed in knots
double waterSpeedT; // transverse water speed in knots
int waterSpeedValid; // indicates if received water speed is valid
double groundSpeedL; // longitudinal ground speed in knots
double groundSpeedT; // transverse ground speed in knots
int groundSpeedValid; // indicates if received ground speed
// is valid
int talker; // code for the device type
}EcVBW_type;

The defines for the bit mask combination of the data field available are as follows:
EC_VBW_WATERSPEED_L 1
EC_VBW_WATERSPEED_T (1<<1)
EC_VBW_WATERSPEED_VALID (1<<2)
EC_VBW_GROUNDSPEED_L (1<<3)
EC_VBW_GROUNDSPEED_T (1<<4)
EC_VBW_GROUNDSPEED_VALID (1<<5)

VHW - Water Speed and Heading

The compass heading to which the vessel points and the speed of the vessel relative to the
water.

1. Heading in degrees - True. Stored in field [Link]

2. Heading in degrees - Magnetic. Stored in field [Link]
3. Speed in knots. Stored in field [Link]
4. Speed in kilometers per hour. Converted into knots and stored in field [Link] if
‘speed in knots’ contains no data
The structure EcVHW_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type

295
EC2007 ECDIS Kernel Programming Guide

int available; // bit mask of filled data fields

time_t timestamp; // time when parsed: sec since 1.1.1970
double headingTrue; // true heading: 0..360 degrees
double headingMagnetic; // magnetic heading: 0..360 degrees
double speed; // speed in knots
int talker; // code for the device type
}EcVHW_type;

The defines for the bit mask combination of the data field available are as follows:
EC_VHW_HEADING_T 1
EC_VHW_HEADING_M (1<<1)
EC_VHW_SPEED (1<<2)

VTG - Course Over Ground and Ground Speed

The actual course and speed relative to the ground.

1. Course over ground in degrees - True. Stored in field [Link]

2. Course over ground in degrees - Magnetic. Stored in field [Link]
3. Speed in knots. Stored in field [Link]
4. Speed in kilometers per hour. Converted into knots and stored in field [Link] if
‘speed in knots’ contains no data
The structure EcVTG_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
double speed; // speed in knots
double courseTrue; // true course: 0..360 degrees
double courseMagnetic; // magnetic course: 0..360 degrees
int talker; // code for the device type
}EcVTG_type;

The defines for the bit mask combination of the data field available are as follows:
EC_VTG_COURSE_T 1
EC_VTG_COURSE_M (1<<1)
EC_VTG_SPEED (1<<2)

ZDA - Time & Date

UTC, day, month, year and local time zone.

296
 EC2007 ECDIS Kernel Programming Guide

1. UTC. Stored in field [Link] in seconds since 1.1.1970

2. Day, 01 to 31. Implicitly stored in field [Link]
3. Month, 01 to 12. Implicitly stored in field [Link]
4. Year. Implicitly stored in field [Link]
5. Local zone description is the number of whole hours added to local time to obtain GMT,
zone description is negative for East longitudes, 0 to 13 hrs. Stored in field
ZDA.zone_hour
6. Local zone minutes description, same sign as local hours. Stored in field ZDA.zone_min
The structure EcZDA_type and all its data fields are listed below:
typedef struct
{
int msgType; // message type
int available; // bit mask of filled data fields
time_t timestamp; // time when parsed: sec since 1.1.1970
time_t utc; // seconds since 1.1.1970
long zone_hour; // hours zone: -13..0..+13 hours
long zone_min; // minutes zone: 0..59 same sign as hours zone
int talker; // code for the device type
}EcZDA_type;

The defines for the bit mask combination of the data field available are as follows:
EC_ZDA_UTC 1
EC_ZDA_ZONE_H (1<<1)
EC_ZDA_ZONE_M (1<<2)

297