sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r870838 - in /websites/staging/sis/trunk/content: ./ source.html
Date Tue, 23 Jul 2013 17:26:04 GMT
Author: buildbot
Date: Tue Jul 23 17:26:03 2013
New Revision: 870838

Staging update by buildbot for sis

    websites/staging/sis/trunk/content/   (props changed)

Propchange: websites/staging/sis/trunk/content/
--- cms:source-revision (original)
+++ cms:source-revision Tue Jul 23 17:26:03 2013
@@ -1 +1 @@

Modified: websites/staging/sis/trunk/content/source.html
--- websites/staging/sis/trunk/content/source.html (original)
+++ websites/staging/sis/trunk/content/source.html Tue Jul 23 17:26:03 2013
@@ -89,13 +89,142 @@ For fetching the source code, choose one
-<h1 id="developers-guide">Developers Guide</h1>
-<p>Some coding practices:</p>
+<p>The remaining of this page provides tips SIS developers.</p>
+<div class="toc">
+<li><a href="#opening-apache-sis-in-an-ide">Opening Apache SIS in an IDE</a><ul>
+<li><a href="#netbeans">NetBeans</a></li>
+<li><a href="#eclipse">Eclipse</a></li>
+<li><a href="#developing-apache-sis">Developing Apache SIS</a><ul>
+<li><a href="#background-knowledge">Background Knowledge</a><ul>
+<li><a href="#geographic-information-systems-and-science">Geographic Information
Systems and Science</a></li>
+<li><a href="#the-isoogc-geospatial-model">The ISO/OGC Geospatial Model</a></li>
+<li><a href="#object-oriented-programming-in-java">Object-Oriented Programming
in Java</a></li>
+<li><a href="#mathematical-background">Mathematical Background</a></li>
+<li><a href="#the-geoapi-interfaces">The GeoAPI Interfaces</a></li>
+<li><a href="#the-sis-library-modules">The SIS library modules</a></li>
+<li><a href="#some-coding-practices">Some coding practices</a></li>
+<h1 id="opening-apache-sis-in-an-ide">Opening Apache SIS in an IDE</h1>
+<p>Different SIS branches are available depending on the target platforms (JDK6 versus
JDK7, or GeoAPI versions).
+The alternatives are listed in the <a href="branches.html">branches page</a>.
+This section documents how to checkout the trunk for development with Subversion,
+but the same instructions should work for any branch or for Git.</p>
+<p>While the primarily SIS build system is Maven, the project provides some IDE configuration
files for developers convenience.
+Before opening the project in an IDE, the source code needs to be downloaded from the source
+and the project built at least once using Maven:</p>
+<div class="codehilite"><pre>svn checkout
+<span class="nb">cd </span>sis
+mvn install
+<h2 id="netbeans">NetBeans</h2>
+<p>NetBeans can open Maven projects natively. This is the recommended approach for
casual working in a small amount of SIS modules.
+For extensive work on Apache SIS or for work impacting many modules, it may be more convenient
and faster to open Apache SIS as a NetBeans project.
+Such pre-configured NetBeans project is available in the <code>ide-project/NetBeans</code>
+This project will fetch dependencies directly from the <code>.m2/repository</code>
local directory,
+and will refer to the resources <code>*.utf</code> files compiled by Maven in
the <code>sis-*/target</code> directories.
+Consequently it is important to run <code>mvn install</code> before opening the
+and after any change in the project dependencies or in the resources.</p>
+<p>Users can customize their project configuration by editing the <code>ide-project/NetBeans/nbproject/private/</code>
+The <code>private</code> directory is excluded by the versioning system, so it
okay to put user-specific information there.
+For example in order to overwrite the default location of the local Maven repository and
to define a system property at execution time,
+one can use:</p>
+<div class="codehilite"><pre><span class="na">maven.repository</span>
<span class="o">=</span> <span class="s">/path/to/my/local/repository</span>
+<span class="na">run.jvmargs</span> <span class="o">=</span> <span
+<h2 id="eclipse">Eclipse</h2>
+<p>Execute the saùe <code>svn checkout</code> to <code>mvn install</code>
commands than in the NetBeans section,
+then execute the following steps:</p>
+<li>Execute <code>mvn eclipse:eclipse</code> on the command line.</li>
+<li>Open Eclipse in a new workspace.</li>
+<li>Go to <em>Eclipse</em> → <em>Preferences</em> →
<em>General</em> → <em>Workspace</em>.</li>
+<li>Change <em>Text file encoding</em> to <em>Other: UTF-8</em>,
press <em>Apply</em>, then <em>Ok</em>.</li>
+<li>Go to <em>File</em> → <em>Import</em> → <em>General</em>
→ <em>Existing Projects in Workspace</em>.</li>
+<li>Choose the <code>sis</code> directory and import.</li>
+<h1 id="developing-apache-sis">Developing Apache SIS</h1>
+<p>Improving and extending SIS requires extensive knowledge of geographic information
+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
+effective computer programming.</p>
+<p>This document is expected to evolve as the SIS project develops its own mode of
+<h2 id="background-knowledge">Background Knowledge</h2>
+<p>All contributors arrive to the project with different knowledge bases, some with
+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
+individual backgrounds we have acquired a list of subjects which we consider critical to
+understanding the SIS project. New contributors are highly encouraged to explore these
+areas if they have no or little knowledge of them.</p>
+<h3 id="geographic-information-systems-and-science">Geographic Information Systems
and Science</h3>
+<p>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
+arise frequently and are worth understanding.</p>
+<p>A good general introduction to the field is the book <em>Geographic Information
Systems and Science</em>
+by Paul A. Longley, Michael F. Goodchild, David J. Maguire and David W. Rhind published in
+second edition by John Wiley and Sons Ltd. in 2004.</p>
+<h3 id="the-isoogc-geospatial-model">The <abbr title="International Organization
for Standardization">ISO</abbr>/<abbr title="Open Geospatial Consortium">OGC</abbr>
Geospatial Model</h3>
+<p>SIS builds on the standards developed through a collaboration between the International
+Organization for Standardization (<abbr title="International Organization for Standardization">ISO</abbr>)
and the Open Geospatial Consortium (<abbr title="Open Geospatial Consortium">OGC</abbr>).
+Contributors to SIS should have at least a basic understanding of the model developed in
+<abbr title="International Organization for Standardization">ISO</abbr> 19000
series of specifications, starting with the Abstract model and working through the
+<em>Feature</em> model. While the <abbr title="International Organization
for Standardization">ISO</abbr> specifications are sold, the <abbr title="Open
Geospatial Consortium">OGC</abbr> releases its own, essentially
+identical versions of standards which have evolved from the collaboration. The <abbr title="Open
Geospatial Consortium">OGC</abbr> specifications
+are available for the <a href=""><abbr title="Open
Geospatial Consortium"><abbr title="Open Geospatial Consortium">OGC</abbr></abbr>
standards and specification</a> page.</p>
+<p>As time progresses, we hope to develop documentation material to introduce the <abbr
title="International Organization for Standardization">ISO</abbr> 19000 specification
+<h3 id="object-oriented-programming-in-java">Object-Oriented Programming in Java</h3>
+<p>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
+<p>Contributors are highly recommended to read the book <em>Effective Java</em>
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.</p>
+<h3 id="mathematical-background">Mathematical Background</h3>
+<p>SIS frequently deals with complex calculations using relatively simple mathematics
+trigonometry and matrix algebra. The coordinate operations of the Referencing modules involve
+trigonometric transformations on a flattened ellipsoid of rotation, the image transformations
+the Coverage modules and in the Rendering system involve extensive use of Affine transforms,
+the Analytic modules often use their own mathematical operations.
+These mathematics cannot be simplified — they reflect the richness of the world around
+<p>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
+Coverage modules. Affines transform coordinates through translation, scaling, rotations,
+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
+There are numerous introductions to affine transformations available on the World Wide Web
+the concept is central to all graphics programming.</p>
+<h3 id="the-geoapi-interfaces">The GeoAPI Interfaces</h3>
+<p>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 <abbr
title="International Organization for Standardization">ISO</abbr>/<abbr title="Open
Geospatial Consortium">OGC</abbr>
+standards in the Java language. GeoAPI therefore defines the core of the model implemented
+by Apache SIS.</p>
+<p>GeoAPI can most easily be learned by exploring the <a href="">GeoAPI
+<h3 id="the-sis-library-modules">The SIS library modules</h3>
+<p>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.</p>
+<h1 id="some-coding-practices">Some coding practices</h1>
 <li>License Header: Always add the current ASF license header as described in <a
href="">ASF Source Header</a>.</li>
-<li>Trailing Whitespaces: Remove all trailing whitespaces. Eclipse users can use Source-&gt;Cleanup
option to accomplish this.</li>
+<li>Trailing Whitespaces: Remove all trailing whitespaces. Eclipse users can use Source-_Cleanup
option to accomplish this.</li>
 <li>Indentation: Use 4 space indents (except for XML files) and never use tabs!
-  Use 2 space indents for XML files, because ISO/OGC XML schemas tend to have a very deep
+  Use 2 space indents for XML files, because <abbr title="International Organization for
Standardization">ISO</abbr>/<abbr title="Open Geospatial Consortium">OGC</abbr>
XML schemas tend to have a very deep structure.</li>
 <li>Line wrapping: Use 120-column line width for Java code and Javadoc.</li>

View raw message