.. _vector.s57:

IHO S-57 (ENC)
==============

.. shortname:: S57

.. built_in_by_default::

International Hydrographic Organisation (IHO) S-57 Electronic Navigation
Charts (ENC) datasets are supported for read access.

The S-57 driver module produces features for all S-57 features in the
S-57 file, and associated updates. S-57 (ENC) files normally have the
extension ".000".

S-57 feature objects are translated into features. S-57 geometry objects
are automatically collected and formed into geometries on the features.

The S-57 reader depends on having two supporting files,
s57objectclasses.csv, and s57attributes.csv available at runtime in
order to translate features in an object class specific manner. These
should be in the directory pointed to by the environment variable
S57_CSV, or in the current working directory.

S-57 update files contain information on how to update a distributed
S-57 base data file. The base files normally have the extension .000
while the update files have extensions like .001, .002 and so on. The
S-57 reader will normally read and apply all updates files to the in
memory version of the base file on the fly. The feature data provided to
the application therefore includes all the updates.

Driver capabilities
-------------------

.. supports_georeferencing::

.. supports_virtualio::

Feature Translation
-------------------

Normally all features read from S-57 are assigned to a layer based on
the name of the object class (OBJL) to which they belong. For instance,
with an OBJL value of 2, the feature is an "Airport / airfield" and has
a short name of "AIRARE" which is used as the layer name. A typical S-57
transfer will have in excess of 100 layers.

Each feature type has a predefined set of attributes as defined by the
S-57 standard. For instance, the airport (AIRARE) object class can have
the AIRARE, CATAIR, CONDTN, CONVIS, NOBJNM, OBJNAM, STATUS, INFORM,
NINFOM, NTXTDS, PICREP, SCAMAX, SCAMIN, TXTDSC, RECDAT, RECIND, SORDAT,
and SORIND attributes. These short names can be related to longer, more
meaningful names using an S-57 object/attribute catalog such as the S-57
standard document itself, or the catalog files (s57attributes.csv, and
s57objectclasses.csv). Such a catalog can also be used to establish all
the available object classes, and their attributes.

The following are some common attributes, including generic attributes
which appear on all feature, regardless of object class. is turned on.

::

     Attribute Name  Description                            Defined On
     --------------  -----------                            ----------

     GRUP            Group number.                          All features

     OBJL            Object label code.  This number        All features
                     indicates the object class of the
                     feature.

     RVER            Record version.

     AGEN            Numeric agency code, such as 50 for    All features
                     the Canadian Hydrographic Service.

     FIDN            Feature identification number.         All features

     FIDS            Feature identification subdivision.    All features

     INFORM          Informational text.                    Some features

     NINFOM          Informational text in national         Some features
                     language.

     OBJNAM          Object name                            Some features

     NOBJNM          Object name in national                Some features
                     language.

     SCAMAX          Maximum scale for display              Some features

     SCAMIN          Minimum scale for display              Some features

     SORDAT          Source date                            Some features

The following are present if LNAM_REFS is enabled:

::

     LNAM            Long name.  An encoding of AGEN,       All features
                     FIDN and FIDS used to uniquely
                     identify this features within an
                     S-57 file.

     LNAM_REFS       List of long names of related features All Features

     FFPT_RIND       Relationship indicators for each of    All Features
                     the LNAM_REFS relationships.


DSID layer
----------

Dataset wide fields, such as DSID (Data Set Identification), DSSI
(Data Set Structure Information) and DSPM (Data Set Parameter) are exposed
in a layer ``DSID`` which has a single feature.
See paragraph 7.3.1 "Data set general information record structure" of
`IHO S-57 Edition 3.1 standard (main)`_

Soundings
---------

Depth soundings are handled somewhat specially in S-57 format, in order
to efficiently represent the many available data points. In S-57 one
sounding feature can have many sounding points. The S-57 reader splits
each of these out into its own feature type \`SOUNDG' feature with an
s57_type of \`s57_point3d'. All the soundings from a single feature
record will have the same AGEN, FIDN, FIDS and LNAM value.

S57 Control Options
-------------------

There are several control options which can be used to alter the
behavior of the S-57 reader. Users can set these by appending them in
the OGR_S57_OPTIONS environment variable.

They can also be specified independently as open options to the driver.

-  **UPDATES**\ =APPLY/IGNORE: Should update files be incorporated into
   the base data on the fly. Default is APPLY.
-  **SPLIT_MULTIPOINT**\ =ON/OFF: Should multipoint soundings be split
   into many single point sounding features. Multipoint geometries are
   not well handle by many formats, so it can be convenient to split
   single sounding features with many points into many single point
   features. Default is OFF.
-  **ADD_SOUNDG_DEPTH**\ =ON/OFF: Should a DEPTH attribute be added on
   SOUNDG features and assign the depth of the sounding. This should
   only be enabled with SPLIT_MULTIPOINT is also enabled. Default is
   OFF.
-  **RETURN_PRIMITIVES**\ =ON/OFF: Should all the low level geometry
   primitives be returned as special IsolatedNode, ConnectedNode, Edge
   and Face layers. Default is OFF.
-  **PRESERVE_EMPTY_NUMBERS**\ =ON/OFF: If enabled, numeric attributes
   assigned an empty string as a value will be preserved as a special
   numeric value. This option should not generally be needed, but may be
   useful when translated S-57 to S-57 losslessly. Default is OFF.
-  **LNAM_REFS**\ =ON/OFF: Should LNAM and LNAM_REFS fields be attached
   to features capturing the feature to feature relationships in the
   FFPT group of the S-57 file. Default is ON.
-  **RETURN_LINKAGES**\ =ON/OFF: Should additional attributes relating
   features to their underlying geometric primitives be attached. These
   are the values of the FSPT group, and are primarily needed when doing
   S-57 to S-57 translations. Default is OFF.
-  **RECODE_BY_DSSI**\ =ON/OFF: Should attribute values be
   recoded to UTF-8 from the character encoding specified in the S57
   DSSI record. Default is OFF.
-  **LIST_AS_STRING**\ =ON/OFF: (GDAL >= 3.2) Whether attributes tagged as list in S57
   dictionaries should be reported as a String field, instead of a StringList.
   Default is OFF. Before GDAL 3.2, the behavior was equivalent to setting
   this option to ON.

Example:

::

   set OGR_S57_OPTIONS = "RETURN_PRIMITIVES=ON,RETURN_LINKAGES=ON,LNAM_REFS=ON"

S-57 Export
-----------

Preliminary S-57 export capability is intended only for specialized use, and is
not properly documented at this time. Setting the following options is a minimum
required to support S-57 to S-57 conversion via OGR.

::

   set OGR_S57_OPTIONS = "RETURN_PRIMITIVES=ON,RETURN_LINKAGES=ON,LNAM_REFS=ON"

The following dataset creation options are supported to supply basic
information for the S-57 data set descriptive records (DSID and DSPM,
see the S-57 standard for a more detailed description):

-  **S57_EXPP**: Exchange purpose. Default is 1.
-  **S57_INTU**: Intended usage. Default is 4.
-  **S57_EDTN**: Edition number. Default is 2.
-  **S57_UPDN**: Update number. Default is 0.
-  **S57_UADT**: Update application date. Default is 20030801.
-  **S57_ISDT**: Issue date. Default is 20030801.
-  **S57_STED**: Edition number of S-57. Default is 03.1.
-  **S57_AGEN**: Producing agency. Default is 540.
-  **S57_COMT**: Comment.
-  **S57_AALL**: Lexical level used for the ATTF fields. Default is 0.
   (GDAL >= 2.4)
-  **S57_NALL**: Lexical level used for the NATF fields. Default is 0.
   (GDAL >= 2.4)
-  **S57_NOMR**: Number of meta records (objects with acronym starting
   with "M\_"). Default is 0.
-  **S57_NOGR**: Number of geo records. Default is 0.
-  **S57_NOLR**: Number of collection records. Default is 0.
-  **S57_NOIN**: Number of isolated node records. Default is 0.
-  **S57_NOCN**: Number of connected node records. Default is 0.
-  **S57_NOED**: Number of edge records. Default is 0.
-  **S57_HDAT**: Horizontal geodetic datum. Default is 2.
-  **S57_VDAT**: Vertical datum. Default is 17.
-  **S57_SDAT**: Sounding datum. Default is 23.
-  **S57_CSCL**: Compilation scale of data (1:X). Default is 52000.
-  **S57_COMF**: Floating-point to integer multiplication factor for
   coordinate values. Default is 10000000. (GDAL >= 2.4)
-  **S57_SOMF**: Floating point to integer multiplication factor for 3-D
   (sounding) values. Default is 10. (GDAL >= 2.4)

See Also
--------

-  `S-57 Online Object/Attribute Catalog <http://www.s-57.com/>`__
-  `Frank's S-57 Page (at
   archive.org) <https://web.archive.org/web/20130730111701/http://home.gdal.org/projects/s57/index.html>`__:
   Links to other resources, and sample datasets.
-  `IHO S-57 Edition 3.1 standard (main)`_
-  `S-57 Appendix B <https://iho.int/uploads/user/pubs/standards/s-57/20ApB1.pdf>`__

.. _`IHO S-57 Edition 3.1 standard (main)`: https://web.archive.org/web/20190330184049/http://www.iho.int/iho_pubs/standard/S-57Ed3.1/31Main.pdf
