.. _crslab:
CRS Lab
=======
This tutorial gives a visual demonstration of coordinate reference systems by displaying
a shapefile and showing how changing the map projection morphs the shape of the features.
Dependencies
------------
Please ensure your pom.xml includes the following::
2.7-SNAPSHOT
org.geotools
gt-shapefile
${geotools.version}
org.geotools
gt-epsg-hsql
${geotools.version}
org.geotools
gt-swing
${geotools.version}
Example
-------
The example code is available
* Directly from svn: CRSLab.java_
* Included in the demo directory when you download the GeoTools source code
.. _CRSLab.java: http://svn.osgeo.org/geotools/trunk/demo/example/src/main/java/org/geotools/demo/CRSLab.java
Main Application
----------------
1. Please create the file **CRSLab.java**
2. Copy and paste in the following code:
.. literalinclude:: ../../../demo/example/src/main/java/org/geotools/demo/CRSLab.java
:language: java
:start-after: // docs start source
:end-before: // docs end main
Customizing JMapFrame
---------------------
Displaying the shapefile
~~~~~~~~~~~~~~~~~~~~~~~~
This method opens and connects to a shapefile and uses a **JMapFrame** to display it. It should look familiar to you from
the :ref:`quickstart` example. Notice that we are customizing the JMapFrame by adding two buttons to its toolbar: one to
check that feature geometries are valid (e.g. polygon boundaries are closed) and one to export reprojected feature data.
.. literalinclude:: ../../../demo/example/src/main/java/org/geotools/demo/CRSLab.java
:language: java
:start-after: // docs start display
:end-before: // docs end display
Validate geometry button action
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This action is implemented as a nested class. Most of the work is done by a helper method in the parent class (see
`Validating feature geometry`_ below).
Note the use of the SwingWorker utility class to run the validation in a background thread. This allows large shapefiles to
be checked without locking up the GUI.
.. literalinclude:: ../../../demo/example/src/main/java/org/geotools/demo/CRSLab.java
:language: java
:start-after: // docs start validate action
:end-before: // docs end validate action
..
.. admonition:: The SwingWorker class
The SwingWorker class is part of Java 6. GeoTools also includes it in the **gt-swing** module for use in
Java 5 applications.
Export button action
~~~~~~~~~~~~~~~~~~~~
This is another nested class that simply delegates to the exportToShapefile method in the parent class.
.. literalinclude:: ../../../demo/example/src/main/java/org/geotools/demo/CRSLab.java
:language: java
:start-after: // docs start export action
:end-before: // docs end export action
Validating feature geometry
---------------------------
This method checks the geometry associated with each feature in our shapefile for common problems (such as polygons
not having closed boundaries).
.. literalinclude:: ../../../demo/example/src/main/java/org/geotools/demo/CRSLab.java
:language: java
:start-after: // docs start validate
:end-before: // docs end validate
Exporting reprojected data to a shapefile
-----------------------------------------
.. literalinclude:: ../../../demo/example/src/main/java/org/geotools/demo/CRSLab.java
:language: java
:start-after: // docs start export
:end-before: // docs end export
Running the application
-----------------------
Swapping between map projections
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When you start the application you will be prompted for a shapefile to display. In the screenshots below we are
using the *bc_border* map which can be downloaded as part of the `uDig sample data`__.
.. _udigdata: http://udig.refractions.net/docs/data-v1_2.zip
__ udigdata_
.. image:: CRSLab_start.png
Click the CRS button at the right-hand end of the status bar and choose *Set the CRS...* from the pop-up menu to
display this chooser dialog:
.. image:: CRSLab_chooser.png
GeoTools includes a very extensive database of map projections drawn from the EPSG reference (see `Some useful links`_ below).
For our example shapefile, an appropriate alternative map projection is *BC Albers* (tip: you can find this quickly in the
chooser list by typing 3005).
When you click OK the map is displayed in the new projection:
.. image:: CRSLab_reprojected.png
Note that when you move the mouse over the map the coordinates are now displayed in metres (the unit of measurement that
applies to the *BC Albers* projection) rather than degrees.
To return to the original projection, open the CRS chooser again and type **4326** for the default geographic projection.
Notice that the map coordinates are now expressed in degrees once again.
Exporting the reprojected data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When you change the map projection for the display the shapefile remains unchanged. With the *bc_border* shapefile, the
feature data are still in degrees but when we select the *BC Albers* projection the features are reprojected on the fly
by GeoTools. To reproject the underlying data we need to export a new shapefile as follows:
* Set the display of reprojected data (e.g. 3005 BC Albers for the *bc_border* shapefile).
* Click the *Validate geometry* button to check feature geometries are ok.
* If there are no geometry problems, click the *Export* button and enter a name and path for the new shapefile.
An alternative export to shapefile method
-----------------------------------------
This version of the export method shows how to use a **Query** object to retrieve reprojected features and write them to
a new shapefile instead of transforming the features 'by hand' as we did above.
.. literalinclude:: ../../../demo/example/src/main/java/org/geotools/demo/CRSLab.java
:language: java
:start-after: // docs start export2
:end-before: // docs end export2
Some useful links
-----------------
`EPSG registry `_
This is *the* place to go to look up map projections. You can search by geographic area, name and type (and, of course, by EPSG code !).
`Online coordinate conversion tool `_
Produced by Jan Jezek and powered by GeoTools.
`Wikibook: Coordinate Reference Systems and Positioning `_
A summary page with some useful definition and links to more detailed information