New contributor

Improving and extending SIS requires extensive knowledge of geographic information science, object oriented programming, the Java language, and of the library itself. Contributors should expect that they will need to learn a great deal before being able to become productive. However, the effort required to become productive should improve the contributor's understanding and knowledge of geographic information systems, of geodetic and geographic science, and of effective computer programming.

This document is expected to evolve as the SIS project develops its own mode of operation.

Background Knowledge

All contributors arrive to the project with different knowledge bases, some with scientific backgrounds, some with a background in computer science, and others with geographic backgrounds or even no training in geographic information science at all. By sharing the richness of our individual backgrounds we have acquired a list of subjects which we consider critical to fully understanding the SIS project. New contributors are highly encouraged to explore these areas if they have no or little knowledge of them.

Geographic Information Systems and Science

While a background in the field is not required, it nonetheless proves exceedingly useful along the way. GIS has developed its own language and has particular concerns which return frequently. Issues of spatial representation, data size, spatial scale, information workflows and other topics arise frequently and are worth understanding.

A good general introduction to the field is the book Geographic Information Systems and Science by Paul A. Longley, Michael F. Goodchild, David J. Maguire and David W. Rhind published in its second edition by John Wiley and Sons Ltd. in 2004. Apache SIS also provides an introduction in the Developer guide.

The ISO/OGC Geospatial Model

SIS builds on the standards developed through a collaboration between the International Organization for Standardization (ISO) and the Open Geospatial Consortium (OGC). Contributors to SIS should have at least a basic understanding of the model developed in the ISO 19000 series of specifications, starting with the Abstract model and working through the Feature model. While the ISO specifications are sold, the OGC releases its own, essentially identical versions of standards which have evolved from the collaboration. The OGC specifications are available for the OGC standards and specification page.

As time progresses, we hope to develop documentation material to introduce the ISO 19000 specification series. Most of the documentation provided by SIS can be found in the Developer guide.

Object-Oriented Programming in Java

SIS is a library designed to be used by other programmers. To play this role effectively, SIS must consider the various ways that users can reuse Java code: not only through object instantiation and method calls but also through inheritance. SIS pays special attention to accessibility constraints ensuring that only the classes and methods which are offered for use are publicly accessible and that these methods are fully and correctly documented in javadoc.

Contributors are highly recommended to read the book Effective Java by Joshua Block, published in its second edition by Addison-Wesley in 2008. The book explains the importance of certain elements in the Java language and discusses subtleties of the language and its use. Most importantly, the book reveals the full scope a programmer must consider when developing a code library.

The Recommended code patterns page also discusses some elements of special importance to Apache SIS.

Mathematical Background

SIS frequently deals with complex calculations using relatively simple mathematics of trigonometry and matrix algebra. The coordinate operations of the Referencing modules involve trigonometric transformations on a flattened ellipsoid of rotation, the image transformations in the Coverage modules and in the Rendering system involve extensive use of Affine transforms, and the Analytic modules often use their own mathematical operations. These mathematics cannot be simplified — they reflect the richness of the world around us.

Affine transformations are not particularly complex but critically important both to the geo-referencing operations of the Referencing modules and to the image transformations of the Coverage modules. Affines transform coordinates through translation, scaling, rotations, and shear, though this latter component is used infrequently in the library. Mathematically, affine transformations are usually applied as a matrix operation applied to a coordinate vector. There are numerous introductions to affine transformations available on the World Wide Web since the concept is central to all graphics programming.

The GeoAPI Interfaces

SIS is build partially as an implementation of the GeoAPI interfaces. GeoAPI defines a set of objects offering particular methods thereby providing an interpretation of the ISO/OGC standards in the Java language. GeoAPI therefore defines the core of the model implemented by Apache SIS.

GeoAPI can most easily be learned by exploring the GeoAPI Javadoc.

The SIS library modules

Contributors should gain a basic understanding of the core library including the separation into modules, the functionality available in the base module, and the functioning of the modules of interest.

Fetching and editing source code

Different SIS branches are available depending on the target platforms. Unless working on a SIS port (e.g. the Android platform), contributors are encouraged to work on the SIS branch targeting the most recent JDK platform (currently JDK8):

svn checkout https://svn.apache.org/repos/asf/sis/branches/JDK8 sis
cd sis
mvn install

The Source code page provides tips for opening the files in an IDE, and guidelines about the way SIS source code is organized.

Committing changes

Copies or displacements of files shall be done with the svn copy or svn move command, respectively. Be aware that not all IDE or graphical tools perform this action appropriately. Always verify on the command-line, at least the first times that a new tools is used, by executing svn status. Files that have been moved or copied shall have a + symbol in the left margin, like below:

D       my-directory/the-old-filename
A  +    my-directory/the-new-filename

Using the proper SVN command is necessary for preserving the history, preserving the SVN properties, and consuming less space on the Apache server hosting the source code repository.

Configuring Subversion properties

Subversion can associate properties to each tracked files. Those properties tell to Subversion how to handle platform-specific aspects like end-of-line characters, and how to serve the files to web browsers (MIME type, encoding, etc.). Those properties are typically set when a new file is added, not during modifications. Developers can specify default properties for all their Subversion working copies as below:

  • Open ~/.subversion/config in an editor, where ~ is the user home directory.
  • Set the enable-auto-props value to yes.
  • Scroll down to the [auto-props] section and make sure to assign the appropriate (usually native) value to the End Of Line (EOL) style of the files to be edited.

Below is an example of a portion of Subversion configuration file (real configuration files are typically larger):

[miscellany]
# Whitespace-delimited globs which Subversion will ignore in its 'status' output.
global-ignores = *.class *.jar .* *~

# Enables automatic properties (defined below) for 'svn add' and 'svn import'.
enable-auto-props = yes

# Section for configuring automatic properties.
# The file-name-pattern can contain wildcards such as '*' and '?'.
# All entries which match will be applied to the file.
[auto-props]
*.java       = svn:mime-type=text/plain;svn:eol-style=native
*.sql        = svn:mime-type=text/plain;svn:eol-style=native
*.txt        = svn:mime-type=text/plain;svn:eol-style=native
*.properties = svn:mime-type=text/plain;svn:eol-style=native
*.xml        = svn:mime-type=text/xml;svn:eol-style=native
*.xsd        = svn:mime-type=text/xml;svn:eol-style=native
*.sld        = svn:mime-type=text/xml;svn:eol-style=native
*.gml        = svn:mime-type=text/xml;svn:eol-style=native
*.xsl        = svn:mime-type=text/xsl;svn:eol-style=native
*.html       = svn:mime-type=text/html;svn:eol-style=native
*.xhtml      = svn:mime-type=text/html;svn:eol-style=native
*.css        = svn:mime-type=text/css;svn:eol-style=native
*.bat        = svn:eol-style=CRLF
*.sh         = svn:eol-style=native;svn:executable
*.bmp        = svn:mime-type=image/bmp
*.png        = svn:mime-type=image/png
*.jpg        = svn:mime-type=image/jpeg
*.jpeg       = svn:mime-type=image/jpeg
*.gif        = svn:mime-type=image/gif
*.tif        = svn:mime-type=image/tiff
*.tiff       = svn:mime-type=image/tiff
*.zip        = svn:mime-type=application/zip
*.utf        = svn:mime-type=application/octet-stream
*.shp        = svn:mime-type=application/octet-stream
*.shx        = svn:mime-type=application/octet-stream
*.dbf        = svn:mime-type=application/octet-stream
README       = svn:mime-type=text/plain;svn:eol-style=native