README: OpENCview project, libS52.so installation notes and disclaimer

Sep 2004
Feb 2009 -update to GTK2, mingw
Jun 2012 -update to EGL/GLES2/ARM (Android/Xoom)


INTRODUCTION:
=============

OpENCview is a project to build an Open Source viewer of
Electronic Navigational Chart (ENC).

This release implement basic rendering of IHO' S-52
(IHO, ECDIS PRESENTATION LIBRARY, USERS' MANUAL, Edition / revision 3.2,
March 2000, Special Publication No. 52 ANNEX A of APPENDIX 2,
published by the International Hydrographic Bureau, MONACO.)
Note that the current Edition of the S-52 specification is 4.2 
and is not available for free download as was Ed. 3.2 
(S52/doc/pslb03_2.pdf) from IHO web site.

This software is not intended for general public but to
interested party in the GIS/marine field.


DISCLAIMER:
===========

OpENCview is not indented for navigational use. It cannot
be used as a paper chart replacement.


SPECIFICATION:
==============

All specification used to code libS52.so are available
for free from the Internet:

organization   specs          specs URL / Implementation URL
------------   -----          ----------------------------

IHO            S-52           IHO S-52 USERS' MANUAL, Ed. 3.2
                              www.iho.shom.fr/general/ecdis/pslb03_2.pdf
                              Implementor: Sylvain Duclos
                              cvs.sourceforge.net:/cvsxroot/openev/contrib/S52

IHO            S-57           IHO S-57 Appendix B.1
                              www.iho.shom.fr/general/ecdis/20USOC.pdf
                              Implementor: Frank Warmerdam
                              gdal.velocet.ca/projects/s57/

OpenGIS        OpenGIS        OpenGIS Abstract Specification
                              www.opengis.org/techno/specs.htm
                              Implementor: Frank Warmerdam
                              gdal.velocet.ca/projects/opengis/

SGI            OpenGL         OpenGL Specification
                              www.opengl.org/developers/documentation/index.html
                              Implementor: Brian Paul
                              www.mesa3d.org

X.Org          X Window Sys.  X Window System
                              www.x.org
                              Implementor: The XFree86 Project Inc.
                              www.xfree86.org

NOTE: http://archive.org maintaint a backup of public IHO files



INSTALLATION:
=============

TL;DR
-----

1.0 - $ cd S52

1.1 - $ make s52glx    - simple testing build for X11
      $ make s52gtk2   - more elaborate testing using GTK2

      --- Other Interesting Targets ---

      $ make s52eglx   - EGL/GLES2 build for X11
      $ make s52eglarm - EGL/GLES2 build for ARM for testing on Android Xoom

OLD WAY (and probably broken)
-----------------------------

1- generate configure for openev:
       $ cd ../../openev
       $ autoconf

2- configure openev:
       $ ./configure  --with-gdal=<your_full_path_to>/gdal \
                     --with-ogr --with-double-geocoord --with-render-plugin

3- compile openev:
       $ make clean
       $ make

4- compile libS52:
       $ cd openev/contrib/S52
       $ make

5- install libS52.so (as root):
       # make install

6- set environnement variable:
       $ export S57_CSV=<path_to_gdal_data_directory>
       $ export OGR_S57_OPTIONS=LNAM_REFS:ON,UPDATES:ON,\
                SPLIT_MULTIPOINT:ON,PRESERVE_EMPTY_NUMBERS:ON,\
                RETURN_LINKAGES:ON

7- test:
       $ openev/openev/gvtest -ogr=<ENC>
    -OR-
       $ openev/contrib/S52/test/s52...
       (s52.cfg will need ENC path ajusted)


MAKEFILE BUILD TARGET:
======================

Various experimental targets are available:

#all: s52glx         # OGR & GLX
#all: s52eglx        # OGR & EGL & X11 (for testing EGL/GLES2 on Linux)
#all: s52eglarm      # OGR & EGL & ARM/Android (for testing EGL/GLES2 on ARM)
#all: s52gv          # GV  (GTK)   using OpenEV/libgv.so
#all: s52gv2         # GV2 (GTK2)
#all: s52gtk2        # OGR & GTK2
#all: s52gtk2p       # profiling
#all: s52qt4         # OGR & Qt4 (same as s52gtk2 but run on Qt4)
#all: s52win32       # same as s52gtk2, run on wine/win32 (MinGW)
#all: s52clutter     # use COGL for rendering text
#all: s52clutter.js  # use COGL for rendering text and Javascript
#all: s52gtk2gps     # same as s52gtk2, used for testing with live data comming from GPSD


MAKEFILE BUILD FLAGS:
=====================

# -DS52_USE_COGL             : used to test text rendering from COGL
# -DS52_USE_FTGL             : text rendering
# -DS52_USE_GLC              : text rendering
# -DS52_USE_FREETYPE_GL      : text rendering, need -DS52_USE_GLES2
# -DS52_USE_LOG              : log every S52_* in tmp file
# -DS52_USE_SUPP_LINE_OVERLAP: suppress display of overlapping line (gdal/ogr need patching, see doc/ogrfeature.cpp.diff)
# -DS52_USE_OGR_FILECOLLECTOR: call OGR S57FileCollector() to apply S57 update
# -DS52_USE_DBUS             : mimic S52.h
# -DS52_USE_SOCK             : same as DBus
# -DS52_USE_PIPE             : same as DBus, in a day
# -DS52_USE_GOBJECT          : for introspection
# -DS52_USE_BACKTRACE        : stack unwinding
# -DS52_USE_PROJ             : use PROJ4
# -DS52_USE_GLIB2            : use glib-2.0
# -DS52_USE_DOTPITCH         : use dotpitch from user
# -DS52_USE_OPENGL_VBO       : GL VBO v1.x and up
# -DS52_USE_EGL              : handle host window manager connection
# -DS52_USE_GLES2            : OpenGL ES 2.0, need -DS52_USE_EGL and -DS52_USE_OPENGL_VBO
# -DS52_USE_WORLD            : experiment to load world shapefile (see S52.c:201)
# -DS52_DEBUG                : internal debug info


FILE LIST:
==========

In openev/contrib/S52 are the following files:

   ChangeLog        -log of code change,
   COYING           -GPL license,
   Makefile         -make instruction to build libS52.so,
   README           -this file,
   S52.c            -front end of S52
   S52.h            -header of S52
   S52.rb           -Ruby binding
   S52CS.c          -S52 Conditional Symbology (CS) instruction
   S52CS.h          -interface to CS,
   S52GL.c          -OpenGL S52 renderer (GL),
   S52GL.h          -interface to GL,
   S52PL.c          -S52 Presentation Library parser (PL),
   S52PL.h          -interface to PL,
   S52raz-3.2.rle   -data: alternate rasterization rules,
   S52raz.s         -to make a .o out of S52raz-3.2.rle
   S52type.h        -header for S52 primitive type,
   S52utils.c       -utilitys,
   S52utils.h       -interface to utilitys,
   S57data.c        -handle S57 data,
   S57data.h        -interface to S57 data,
   S57gv.c          -connect to OpenEV (gv)
   S57gv.h          -interface
   S57ogr.c         -connect to OGR data,
   S57ogr.h         -interface
   TODO             -jot pad for missing stuff,
   gvS57layer.c     -plugin entree point / interface to openev (static link),
   gvS57layer.h     -interface to plugin
                     (for completness -useless in real life),

   lib/freetype_gl/ -GL freetype rendering from Nicolas P. Rougier
                     http://code.google.com/p/freetype-gl/

   lib/tesselator/  -tesselator from Mesa3D

   doc/
   C1.dispCatSwitch.txt -list of objects that switch IHO layers depending on attributes
   obj.txt              -S57 objects
   att.txt              -S57 attributes

   doc/symbol/
   boylat24.dia    -BOYLAT24 object construct (Dia)
   boylat24.png    -boylat24.dia converted to PNG

   doc/html/       -html doc of S52.h using
                    https://github.com/GNOME/introspection-doc-generator

   test/
   Makefile        -build test harness for target
   REAME           -notes for test
   s52glx.c        -harness for X
   s52gv.c         -harness for GV
   s52gtk2.c       -harness for GTK2
   s52gtk2.rb      -same thing but in Ruby
   s52.cfg         -local configuration (debug)
   s52egl.c        -EGL harness for X and Android
   s52ais.c        -GPSD client that feed AIS data to libS52.so
   sl4agps.c       -UI/GPS/Gyro from Android via SL4A (RPC Bridge to Android)


REQUIREMENT:
============

-OpenEV2 (front end - facultative),

-GDAL (S57) (tip: use 'export CPL_DEBUG=on'),

-PROJ4 (projection),

-lcms (color management system),

-A Presentation Library .DAI file his also required for symbolizing S57.
As of this writing the current Official Presentation Library
is Edition 4.2, and is available directly from the IHB
(International Hydrographic Bureau) at info@ihb.mc.
In the absence of an Official IHO Presentation Library
an alternate non-conforming ECDIS library is used (S52raz-3.2.rle.)


LINKS:
======

Frank Warmerdam web site has a bunch of links:
http://home.gdal.org/projects/s57/index.html


CREDIT:
=======

Frank Warmerdam (warmerdam at pobox dot com) OpenEV/GDAL/OGR/S-57.
Christian Gebauer Tveen (cgt at navicon dot dk) GV/OGR split.


LICENSE:
========

LGPL3



Comment / inquiry are welcome,

Sylvain Duclos
sduclos@users.sf.net