GeoTools

OSGeo

Table Of Contents

Previous topic

Java EE

Next topic

Building

This Page

Frequently Asked Questions

This page brings together the individual faq pages for each module. This allows you to search for an answer even if you are not sure exactly what module is responsible.

Please direct any comments or suggestions about this page to the GeoTools user list.

GeoTools FAQ

Q: What is GeoTools ?

GeoTools is a free, open source Java geospatial toolkit for working with both vector and raster data. It is made up of a large number of modules that allow you to:

  • access GIS data in many file formats and spatial databases
  • work with an extensive range of map projections
  • filter and analyze data in terms of spatial and non-spatial attributes
  • compose and display maps with complex styling
  • create and analyze graphs and networks

GeoTools implements specifications of the Open Geospatial Consortium including:

  • Simple Features
  • GridCoverage
  • Styled Layer Descriptor
  • Filter Encoding

GeoTools can be readily extended by adding new modules, either for custom applications or as contributions to the library.

Q: How do I search the archives of the GeoTools mailing lists?

Go to this page.

Q: What are the features of the GeoTools Library?

That is a hard question to answer as GeoTools is a general purpose geospatial library.

Here is a sample of some of the great features in the library today:

  • Supports OGC Grid Coverage implementation
  • Coordinate reference system and transformation support
  • Symbology using OGC Styled Layer Descriptor (SLD) specification
  • Attribute and spatial filters using OGC Filter Encoding specification
  • Supports graphs and networks
  • Java Topology Suite (JTS) - with support for the OGC Simple Features Specification - used as the geometry model for vector features.
  • A stateless, low memory renderer, particularly useful in server-side environments
  • Powerful “schema asisted” parsing technology using XML Schema to bind to GML content
  • Interact with OGC web services with both Web Map Server and Web Feature Server support
  • Open plug-in system allowing you to teach the library additional formats
  • Plug-ins for the ImageIO-EXT project allowing GeoTools to read additional raster formats from GDAL

Q: Okay what data formats does GeoTools support?

GeoTools supports additional formats through the use of plug-ins. You can control the formats supported by your application by only including the plug-ins you requrie.

  • arcgrid
  • arcsde
  • db2
  • raster formats
    • geotiff
    • grassraster
    • gtopo30
    • image - world plus image files using common image formats such as JPEG, TIFF, GIF and PNG
    • imageio-ext-gdal (allows access to additional GDAL formats thanks to the ImageIO project)
    • imagemoasaic
    • imagepyramid
    • JP2K
  • Database “jdbc-ng” support
    • h2
    • mysql
    • oracle
    • postgis
    • spatialite
    • sqlserver
  • postgis
  • property - simple text file format often used for testing
  • shapefile

Perhaps one of the unsupported modules or plugins may have what you need. These modules are supplied by the community and do not yet meet the quality expected by the library:

There are also some “unsupported” formats that are either popular or under development:

  • app-schema (under development) - allows the remapping and combining of one or more data sources into a provided application schema
  • dfx
  • edigeo
  • geojson
  • wfs

The current authoritative list of plugins is of course the source code:

GeoTools versions

Q. How are GeoTools versions organized?

Like many open source projects, GeoTools has a development version and one or more stable versions active at any given time. By active, we mean that the project developers are working on new features, improvements and bug fixes.

Source code for the stable branch(es) can be found in the branches folder of the GeoTools subversion repository. For example, at the time of writing the active stable branch is branches/2.7.x.

Formal releases are based on a stable branch. The source code for a formal release is archived in the tags folder of the subversion repository. For example, the version 2.7.1 sources can be found in tags/2.7.1.

Source code for the development version are in the trunk folder. This is the bleeding edge code where the latest features are being worked on. Eventually this code will become the next stable branch.

Commencing with GeoTools version 8, a major.minor.patch numbering system applies.

major
An increment of the major identifier (e.g. from version 8.x.y to 9.0.0) indicates substantial changes that can break binary compatibility with previous versions.
minor
An increment in the minor identifier (e.g. from version 8.0.y to 8.1.y) indicates new features and/or improvements that do not break binary compatibility with the previous version.
patch
An increment in the patch identifier (e.g. from version 8.0.0 to 8.0.1) indicates fixes and minor tweaks since the previous version.

Q. What is a SNAPSHOT version and how do I use it?

A snapshot is the GeoTools code that the developers are actively working on. Usually there will be two active snapshots: one associated with the most recent formal release (e.g GeoTools 2.7-SNAPSHOT) and a second for the development version (e.g. GeoTools 8-SNAPSHOT). At times there will also be snapshot releases for an earlier stable branch that is still being maintained (e.g. GeoTools 2.6-SNAPSHOT).

New snapshot jars are built nightly and deployed to a repository separate from the one used for formal releases. If you are using Maven as your build tool you can work with a snapshot release by adding the following to your pom.xml:

<repository>
    <id>opengeo</id>
    <name>OpenGeo Maven Repository</name>
    <url>http://repo.opengeo.org/</url>
    <snapshots>
        <enabled>true</enabled>
    </snapshots>
</repository>

You can now build your project against a snapshot release by setting it as the your version property as shown here:

<properties>
    <geotools.version>8-SNAPSHOT</geotools.version>
</properties>

Common License Questions

Q: What licence does GeoTools use?

All GeoTools modules are released under the GNU Lesser General Public License (LGPL). GeoTools can be used for commercial applications, any changes made to GeoTools need to be made available to your customers.

An easy way to do this is to contribute the changes back to the GeoTools project (but this is not required).

Q: Can I use GeoTools in my Commercial Project?

Yes. This is one of the reasons we chose the LGPL license. You can build a Commercial application which uses GeoTools as a library and re-distribute your application under any license you choose. Your users will get a license to your application under the terms of your license and a license to the GeoTools library under the terms of the LGPL. You only need to give your users some way to get the source code of the GeoTools library, most easily by pointing your users to the servers of the GeoTools project.

However, if you choose to modify the GeoTools library itself, then you have to publish the source code to those changes to the users of your application.

The easiest way to do that will be to submit those changes back to the GeoTools project so the changes can be incorporated into the core source code.

Q: Can I use GeoTools in my GPL Project?

Yes. This is one of the reasons we chose the LGPL license. You can build a free software application which uses GeoTools as a library and re-distribute your application under the GPL license. Your users will get a license to your application under the terms of the GPL and a license to the GeoTools library under the terms of the LGPL. You only need to give your users some way to get the source code of the GeoTools library, either by pointing your users to the servers of the GeoTools project or by giving them the GeoTools code in the same way you give them the code to your GPL application.

However, if you choose to modify the GeoTools library itself, then you have to publish the source code to those changes to your users.

The easiest way to do that will be to submit those changes back to the GeoTools project so the changes can be incorporated into the core source code.

Note

This means you can use GeoTools as a library but you cannot incorporate GeoTools code directly into your GLP application. Legally, the latter amounts to re-licensing GeoTools under a new license and you do not have the right to do so.

Q: What restrictions are there on my use of GeoTools?

None. You can read, run, copy, or do anything else you want to do with the GeoTools code. This is one of the four core freedoms of free software which we grant you under the LGPL: the freedom to use the software for any purpose you choose.

The only restrictions of the LGPL come when you are re-distributing GeoTools, that is when you are passing it on to someone else either on its own or as part of a larger product, such as when you share it or sell it.

Q: What restrictions are there on my re-distribution of GeoTools?

Technically, you have to provide everyone who receives a copy of GeoTools from you with some way to get the source code to the library. In practice, pointing those users to the Geotools project itself is considered an adequate solution.

However, if you are re-distributing a modified version of GeoTools then you need to provide users with access to the modified code. This means that you must give your users some way to get the modified code such as by publishing it yourself. An alternative way to provide your users with the modifications would be to work with us to get your changes integrated into the GeoTools library– -you could then use the new library directly. The best way to do this would be to open a change request on our issue tracker and add to that request a code patch containing your changes.

Q: What should I do if I am still unsure what I am allowed to do?

You can clarify any questions you have by sending us questions to the user mailing list:

Q: Why can’t I find module X in the GeoTools distribution or javadocs?

If you’re working with a recent GeoTools release then chances are the module that you’re looking for is an unsupported module. These modules not part of the standard GeoTools distribution but are available from the Subversion repository in the modules/unsupported folder. If you are using Maven as your build tool you can include a dependency for an unsupported module as you would any other GeoTools module.

Q: What is an unsupported module?

Unsupported modules are those found in the modules/unsupported folder of each GeoTools version in the Subversion repository. They are not part of the standard GeoTools distribution but are still available for use via Subversion, Maven and manual download.

A module can be unsupported for one or more of the following reasons:

  • It is under development and has not yet met all of the criteria for usability, test coverage, documentation etc to be included in the general GeoTools distribution.
  • It lacks a module maintainer.
  • It has been superseded by another module and dropped from the general distribution, but still has enough useful bits or active users to make it worth keeping (at least for a while).

Unsupported modules are a mixed bag: some are reliable and regularly used while others are in various states of development or decay. The best way to find out the status of any particular module is to look in the user list archives and then, if you want to check further, post a question to the list.

OpenGIS FAQ

Q: Relationship with “GeoAPI”?

  • GeoAPI was started in 2002 James McGill (who also set up GeoTools). The aim at that time was to provide common API for independent projects like GeoTools, deegree and OpenJump, allowing the easy exchange of code.
  • Later on, the Open Geospatial consortium started the “GO-1” project with a similar goal. The “Geospatial Object” project was led Polexis which was at the time based in the United States.
  • Givin the similarity between GO-1 and GeoAPI goals, we got in touch each other and managed to merge the two projects.
  • Polexis produces the following official OGC specification based on GeoAPI 2.0: http://www.opengeospatial.org/standards/go
  • Later Polexis was bough by Sys Technology, with the new owner and priorites their investment in GeoAPI / GO-1 stopped.
  • The GO-1 / GeoAPI working group at OGC was dissolved du to lack of activity.
  • GeoTools contributors gradually over the GeoAPI project and in GeoTools 2.7 folded these interfaces back into the GeoTools OpenGIS module

JTS FAQ

Q: What is the relationship between JTS and GeoTools?

We make use of the Java Topology Suite to represent “Simple” Geometry, and the OpenGIS interfaces to represent everything else. We have been forced to define an API module of our own in a few cases, like data access, where something “standard” is not available.

You will be using JTS a lot as it literally is the “shape” of GeoTools. It captures shapes using constructs like Coordinate, Point, Polygon and LineString.

  • Do keep in mind that JTS is pure topology and the Geometry objects are pure shapes with no meaning. For the meaning, placing that shape on the earth, you will need to consult a CoordinateReferenceSystem.
  • JTS topologic operations work in a two dimensional cartesian plane. With this in mind three dimensional shapes can be represented, but not calculated with.
  • JTS focuses on linear topology, you will need to represent curves as a LineString with many little segments.

With those notes it may sound like JTS is limited; it is instead focused on the task at hand - Geographic Information Systems. While 3D and curves may be common in CAD systems we will need a lot of funding and raw science to make it work for GIS. Some of that work is happening in GeoTools with ISO Geometry.

Q: What Geometry Specifications?

JTS is an implementation of the OGC Simple Features for SQL Specification (ie SFSQL). It covers 2D constructs like Point, Line and Polygon. JTS is willing to carry a 3rd point around but does not use it for calculations - making it a 2.5D solution for cartesian space.

Specification Supports Implementation
Simple Features for SQL 2.5D, linear Java Topology Suite
ISO Geometry 3D, curves OpenGIS ISO Geoemtry interfaces

GeoTools makes a point of working with both implementations, but frankly the ISO Geometry implementations are not ready yet.

API FAQ

Q: What does API mean?

An “Application Program Interface” (API) is is a contract that GeoTools commits to using to make functionality available to your application.

The interfaces in gt-opengis and gt-api represent the formal GeoTools interfaces advertises to your application defining concepts ideas and data structures.

Additional public methods and classes are added by other modules, but they are focused on doing rather than defining.

For more information review welcome How to Use GeoTools page.

Metadata FAQ

Q: Utility Classes?

GeoTools also includes utility classes used to support the implementation of GeoTools.

For the most part these classes are considered internal, as an example to iron out differences between Java versions.

Q: Where are the Interfaces for Metadata?

The interfaces are in the gt-opengis module.

If you don’t have access to the ISO documentation (who does?) just reading the javadocs is a great place to start.

Q: Why did you implement this class it is in Java 6?

If you are running Java 6 feel free to use Java 6 facilities.

Some of the utility classes are just here to get the job done in Java 1.4 - they have nothing to do with spatial anything. You will find examples of checked collections (yes I know that is available in Java 5); an implementation of an object cache (there is a JSR for that); and so on ...

Q: Why are these utility classes in the Metadata Module?

Because metadata is the “lowest” implementation jar in our software stack; needed by everyone else. These classes really are not interesting enough to separate out into their own module.

Q: Why does gt-metadata contain all this factory stuff?

The gt-metadata module introduces some of the “glue code” needed used to hook up GeoTools to services provided by your project. You will find pages here covering logging and JNDI integration.

For a more detailed discussion of how to integrate GeoTools into your application please review the advanced section on integration.

Referencing FAQ

Q: Why can’t I display shapefile over a WMS layer?

This can happen when the axis definition (ie. which way is X ?) differs between the coordinate reference system used by the shapefile and that used by the WMS layer. It can be fixed by requesting GeoTools to enforce lon - lat axis order by including this statement in your code prior to displaying layers...

Hints.putSystemDefault(Hints.FORCE_LONGITUDE_FIRST_AXIS_ORDER, Boolean.TRUE);

If this doesn’t work you can try this more brutal, System wide approach...

System.setProperty("org.geotools.referencing.forceXY", "true");

See also:

Q: How to choose an EPSG Authority?

The referencing module does not do very much out of the box - it needs someone
to tell it what all the funny codes mean (such as “EPSG:4326”).

You need to choose a single “epsg” jar to have on your classpath; if you have several epsg jars on your classpath you will get a FactoryException.

For most needs just use the gt-epsg-hsql plugin:

  • gt-epsgh-hsql: will unpack an hsql database containing the official epsg database into a temp directory, a great solution for desktop applications.

There are several alternatives:

  • gt-epsg-wkt: uses an internal property file and is lightweight rather than official and correct. A great solution for applets
  • gt-epsg-postgres: uses the official epsg database which you have to load into PostgreSQL yourself. A great solution for Java EE applications.
  • gt-epsg-access: irectly use an the official epsg database as distributed. A great solution for windows users that need the latest official database.

Unsupported:

  • gt-epsg-oracle: Load the official epsg database into oracle to use this plugin
  • gt-epsgh-h2: use this popular pure java database

Q: Are other authorities other than EPSG supported?

The main module includes definitions of AUTO and AUTO2 and several other OGC inspired ideas.

Q: What Jars does gt-referencing need?

As an example to use gt-epsg-hsql you will need:

C:\geotools\trunk\modules\plugin\epsg-hsql>mvn dependency:tree
...
------------------------------------------------------------------------
Building EPSG Authority Service using HSQL database
   task-segment: [dependency:tree]
------------------------------------------------------------------------
[dependency:tree]
org.geotools:gt2-epsg-hsql:jar:2.5-SNAPSHOT
+- junit:junit:jar:3.8.1:test
+- javax.media:jai_core:jar:1.1.3:provided
+- org.geotools:gt2-referencing:jar:2.5-SNAPSHOT:compile
|  +- java3d:vecmath:jar:1.3.1:compile
|  +- commons-pool:commons-pool:jar:1.3:compile
|  \- org.geotools:gt2-metadata:jar:2.5-SNAPSHOT:compile
|     +- org.opengis:geoapi:jar:2.2-SNAPSHOT:compile
|     +- javax.units:jsr108:jar:0.01:compile
|     \- edu.oswego:concurrent:jar:1.3.4:compile
+- org.geotools:gt2-sample-data:jar:2.5-SNAPSHOT:test
+- hsqldb:hsqldb:jar:1.8.0.7:compile
+- net.sourceforge.groboutils:groboutils-core:jar:5:test
\- commons-dbcp:commons-dbcp:jar:1.2.2:test
------------------------------------------------------------------------

Q: Bursa-Wolf Parameters Required?

GeoTools performs datum shift using Bursa-Wolf parameters at this time. If these cannot be determined from your CoordinateReferenceSystem we will be unable to sort out a transform.

Most of the time this does not matter as users work with their information in the same datum it was collected in.

  • A: Lenient

    A quick fix involves setting “lenient ” to true when searching for a MathTransform.:

    MathTransform transform = CRS.findMathTransform(sourceCRS, targetCRS, true);

    This approach is good enough for display, but not recommended for editing or careful analysis work.

  • A: Match your PRJ file

    Usually this occurs when you have loaded a CoordinateReferenceSystem from a “prj” file included with your shapefile.

    To fix look up the complete definition in the EPSG database using the CRS utility class. The EPSG database contains more information than can be Expressed in your “prj” file.

  • A: Datum shift by Grid

    Finally in the rare case of a Datum shift backed by grids are only partially implemented. Rueben Shulz has implemented data shift backed by grids for NADCON with the following limitations:

    • Use of NADCON grids has not been integrated with DefaultCoordinateOperationFactory (so you would need to set it up by hand)
    • The general case of a Datum shift provided by a grid is not covered, for example Spanish Datum Changes ED50-ETRS89 will not work

Q: What does gt-referencing do?

You will eventually care about this as it defines how 2D data actually means 3D data.

You can take a measurement (ie a coordinate) plus a coordinate reference system (the meaning) and figure out where a position on the earth is in 3D space.

It is easy to assume that Coordinates are recorded in double[] as repeating x/y values as is often done in CAD programs.

In a GIS application we can only wish they are X,Y. They are actually LAT/LONG or LONG/LAT or angle,angle,angle or something crazy like time.

Given two CoordinateReferenceSystems you can make a math transform from one to the other. So you could take angle/angle/angle and munch it into something you like for 3D or 2D display.

We will get into this again when you actually have some data - the CoordinateReferenceSystem will tells you what the data “means”.

Much like 3.0 and “three meters”. The first is a number, and the second one means a length.

Q: Can I just use Referencing without the rest of GeoTools?

Yes, you will need to use the metadata module, and one of the epsg modules. Along with their dependencies such as units.

Q: I cannot find an EPSG Code?

You need to have one, and only one, of the epsg plugins on your CLASSPATH. We recommend epsg-hsql for most uses.

Q: I cannot re-project my shapefile (missing “Bursa wolf parameters”)?

This error occurs when you try to re-project a shapefile with a custom coordinate reference system:

MathTransform transform = CRS.findMathTransform(DefaultGeographicCRS.WGS84, moroccoCRS);

This problem often occurs when working with a custom coordinate reference system, if you look in your shapefile’s prj file you will see that the contents is normal “well known text”.

The “Bursa-Wolf parameters” define the relationship (and a transformation) between the spheroid being used by your shapefile and the normal WGS84 spheroid.

The opengis javadocs has some help for you here:

Your best bet is to look up the normal EPSG code for your area; and update your “prj” file to include the official definition.

Q: How do I Transform?

The MathTransform interface is used to transform (or “re-project”) one DirectPosition at a time.

You can also use the utility class JTS which has helper methods to transform a Geometry.

Q: How to Transform a Geometry?

You can use the JTS utility class to create a new geometry in the desired projection:

MathTransform transform = CRS.findMathTransform(sourceCRS, targetCRS, false);
Geometry targetGeometry = JTS.transform( sourceGeometry, transform);

Q: How to Transform an Envelope?

For a referenced envelope you can transform directly:

    CoordinateReferenceSystem sourceCRS = CRS.decode("EPSG:4326");
    ReferencedEnvelope envelope = new ReferencedEnvelope(0, 10, 0, 20, sourceCRS);
    
    // Transform using 10 sample points around the envelope
    CoordinateReferenceSystem targetCRS = CRS.decode("EPSG:23032");
    ReferencedEnvelope result = envelope.transform(targetCRS, true, 10);

For a JTS Envelope use the JTS utility class:

    CoordinateReferenceSystem sourceCRS = CRS.decode("EPSG:4326");
    CoordinateReferenceSystem targetCRS = CRS.decode("EPSG:23032");
    
    Envelope envelope = new Envelope(0, 10, 0, 20);
    
    MathTransform transform = CRS.findMathTransform(sourceCRS, targetCRS);
    
    Envelope quick = JTS.transform(envelope, transform);
    
    // Sample 10 points around the envelope
    Envelope better = JTS.transform(envelope, null, transform, 10);

Q: How to Transform a GridCoverage?

You can use a resample operation to produce a GridCoverage in the desired projection.

Q: How do I extend the system with my own custom CRS?

If you wish to act as your own authority you can register an additional factory with the system.

This is often used by those working with a national standards body that maintains its own set of official codes.

You can use the gt-epsg-wkt plugin as an example of the following options:

  • Through a property file and programatic registration of the factory

    You can create a file with your CRS in the WKT format, instantiate a PropertyAuthorityFactory with that CRS:

    1. Create a property file with your CRS definitions in Well-Known Text (WKT) format.
    2. Each line of the file should be “someUniqueCodeValue = crsInWKT”.
    3. Place that file as a resource available from your code at run time
    4. Create a org.geotools.referencing.factory.PropertyAuthorityFactory with a custom code for the authority such as “CUSTOM” and a URI to your file
    5. Register your factory with the ReferencingFactoryFinder.addAuthorityFactory(..) method

    After that, the desired CRS can be invoked as “CUSTOM:someUniqueCodeValue” so, for example, a CRS object can be created using the CRS.decode(..) method with the string nomenclature of authority-colon-code. The CRS’s defined in this way will also be taken into consideration by the rest of the referencing subsystem.

  • Through a property file and automatic registration of the factory

    A more sophisticated approach changes step 3 to create a new class which both extends PropertyAuthorityFactory and has a no argument constructor which calls the parent with the right URI argument. Such a class will be picked up automatically when the factory system is initialized so step 4 in the list above is no longer necessary.

Q: How to I add my own EPSG Codes?

The gt-epsg-wkt plugin is intended to be used on its own and should not be combined with any of the other gt-epsg-h2, or gt-epsg-hsql plugins as they will end up in conflict.

If you want to add a few more definitions over and above those provided by the official database (ie epsg-hsql or epsg-h2) please use the following (taken from the uDig application):

URL url = new URL(url, "epsg.properties");
// application directory or user directory?
// where you are looking for epsg.properties
if ("file".equals(proposed.getProtocol())) {
    File file = new File(proposed.toURI());
    if (file.exists()) {
        epsg = file.toURI().toURL();
    }
}
// you may try several locations...
if (epsg != null) {
    Hints hints = new Hints(Hints.CRS_AUTHORITY_FACTORY, PropertyAuthorityFactory.class);
    ReferencingFactoryContainer referencingFactoryContainer =
               ReferencingFactoryContainer.instance(hints);

   PropertyAuthorityFactory factory = new PropertyAuthorityFactory(
                      referencingFactoryContainer, Citations.fromName("EPSG"), epsg);

   ReferencingFactoryFinder.addAuthorityFactory(factory);
   ReferencingFactoryFinder.scanForPlugins(); // hook everything up
}

Here is an example ::download::epsg.properties </artifacts/epsg.properties>. file used by uDig:

18001=PROJCS["Geoscience Australia Standard National Scale Lambert Projection",GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS_1978",6378135,298.26],TOWGS84[0,0,0]],PRIMEM["Greenwich",0],UNIT["Decimal_Degree",0.0174532925199433]],PROJECTION["Lambert_Conformal_Conic_2SP"],PARAMETER["central_meridian",134.0],PARAMETER["latitude_of_origin",0.0],PARAMETER["standard_parallel_1",-18.0],PARAMETER["standard_parallel_2",-36.0],UNIT["Meter",1]]
41001=PROJCS["WGS84 / Simple Mercator",GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS_1984",6378137,298.257223563]],PRIMEM["Greenwich",0],UNIT["Decimal_Degree",0.0174532925199433]],PROJECTION["Mercator_1SP"],PARAMETER["central_meridian",0],UNIT["Meter",1]]
42101=PROJCS["WGS 84 / LCC Canada",GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS_1984",6378137,298.257223563]],PRIMEM["Greenwich",0],UNIT["Decimal_Degree",0.0174532925199433]],PROJECTION["Lambert_Conformal_Conic_2SP"],PARAMETER["central_meridian",-95.0],PARAMETER["latitude_of_origin",0],PARAMETER["standard_parallel_1",49.0],PARAMETER["standard_parallel_2",77.0],PARAMETER["false_northing",-8000000.0],UNIT["Meter",1]]
42102=PROJCS["BC_Albers",GEOGCS["GCS_North_American_1983",DATUM["North_American_Datum_1983",SPHEROID["GRS_1980",6378137,298.257222101],TOWGS84[0,0,0]],PRIMEM["Greenwich",0],UNIT["Degree",0.017453292519943295]],PROJECTION["Albers_Conic_Equal_Area"],PARAMETER["False_Easting",1000000],PARAMETER["Central_Meridian",-126],PARAMETER["Standard_Parallel_1",50],PARAMETER["Standard_Parallel_2",58.5],PARAMETER["Latitude_Of_Origin",45],UNIT["Meter",1]]
42103=PROJCS["WGS 84 / LCC USA",GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS_1978",6378135,298.26]],PRIMEM["Greenwich",0],UNIT["Decimal_Degree",0.0174532925199433]],PROJECTION["Lambert_Conformal_Conic_2SP"],PARAMETER["central_meridian",-100.0],PARAMETER["latitude_of_origin",0],PARAMETER["standard_parallel_1",33.0],PARAMETER["standard_parallel_2",45.0],UNIT["Meter",1]]
42104=PROJCS["NAD83 / MTM zone 8 Québec",GEOGCS["GRS80",DATUM["GRS_1980",SPHEROID["GRS_1980",6378137,298.257222101]],PRIMEM["Greenwich",0],UNIT["Decimal_Degree",0.0174532925199433]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",-73.5],PARAMETER["scale_factor",0.9999],PARAMETER["false_easting",304800],UNIT["Meter",1]]
42105=PROJCS["WGS84 / Merc NorthAm",GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS_1984",6378137,298.257223563]],PRIMEM["Greenwich",0],UNIT["Decimal_Degree",0.0174532925199433]],PROJECTION["Mercator_1SP"],PARAMETER["central_meridian",-96],UNIT["Meter",1]]
42106=PROJCS["WGS84 / Lambert Azim Mozambique",GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS_1984",6378137,298.257223563]],PRIMEM["Greenwich",0],UNIT["Decimal_Degree",0.0174532925199433]],PROJECTION["Lambert_Azimuthal_Equal_Area"],PARAMETER["latitude_of_origin",5],PARAMETER["central_meridian",20],UNIT["Meter",1]]
42301=PROJCS["NAD27 / Polar Stereographic / CM=-98",GEOGCS["NAD27",DATUM["North_American_Datum_1927",SPHEROID["Clarke 1866",6378206.4,294.978698213901],TOWGS84[-9,151,185]],PRIMEM["Greenwich",0],UNIT["degree",0.0174532925199433]],PROJECTION["Stereographic"],PARAMETER["latitude_of_origin",90],PARAMETER["central_meridian",-98.0],PARAMETER["scale_factor",0.9996],UNIT["Meter",1]]
42302=PROJCS["JapanOrtho.09 09",GEOGCS["Lon/Lat.Tokyo Datum",DATUM["Tokyo Datum",SPHEROID["anon",6377397.155,299.15281310608]],PRIMEM["Greenwich",0],UNIT["Degree",0.0174532925199433]],PROJECTION["Transverse_Mercator"],PARAMETER["Central_Meridian",139.833333333333],PARAMETER["Latitude_of_Origin",36],PARAMETER["Scale_Factor",0.9999],UNIT["Meter",1]]
42303=PROJCS["NAD83 / Albers NorthAm",GEOGCS["NAD83",DATUM["North_American_Datum_1983",SPHEROID["GRS_1980",6378137,298.257222101],TOWGS84[0,0,0]],PRIMEM["Greenwich",0],UNIT["Decimal_Degree",0.0174532925199433]],PROJECTION["Albers_conic_equal_area"],PARAMETER["central_meridian",-96.0],PARAMETER["latitude_of_origin",23],PARAMETER["standard_parallel_1",29.5],PARAMETER["standard_parallel_2",45.5],UNIT["Meter",1]]
42304=PROJCS["NAD83 / NRCan LCC Canada",GEOGCS["NAD83",DATUM["North_American_Datum_1983",SPHEROID["GRS_1980",6378137,298.257222101],TOWGS84[0,0,0]],PRIMEM["Greenwich",0],UNIT["Decimal_Degree",0.0174532925199433]],PROJECTION["Lambert_Conformal_Conic_2SP"],PARAMETER["central_meridian",-95.0],PARAMETER["latitude_of_origin",49.0],PARAMETER["standard_parallel_1",49.0],PARAMETER["standard_parallel_2",77.0],UNIT["Meter",1]]
42305=PROJCS["France_II",GEOGCS["GCS_NTF_Paris",DATUM["Nouvelle_Triangulation_Francaise",SPHEROID["Clarke_1880_IGN",6378249.2,293.46602]],PRIMEM["Paris",2.337229166666667],UNIT["degree",0.0174532925199433]],PROJECTION["Lambert_Conformal_Conic_2SP"],PARAMETER["False_Easting",600000],PARAMETER["False_Northing",2200000],PARAMETER["Central_Meridian",0],PARAMETER["Standard_Parallel_1",45.898918964419],PARAMETER["Standard_Parallel_2",47.696014502038],PARAMETER["Latitude_Of_Origin",46.8],UNIT["Meter",1]]
42306=PROJCS["NAD83/QC_LCC",GEOGCS["NAD83",DATUM["North_American_Datum_1983",SPHEROID["GRS_1980",6378137,298.257222101],TOWGS84[0,0,0]],PRIMEM["Greenwich",0],UNIT["Decimal_Degree",0.0174532925199433]],PROJECTION["Lambert_Conformal_Conic_2SP"],PARAMETER["central_meridian",-68.5],PARAMETER["latitude_of_origin",44],PARAMETER["standard_parallel_1",46],PARAMETER["standard_parallel_2",60],UNIT["Meter",1]]
42307=PROJCS["NAD83 / Texas Central - feet",GEOGCS["NAD83",DATUM["North_American_Datum_1983",SPHEROID["GRS 1980",6378137,298.257222101],TOWGS84[0,0,0]],PRIMEM["Greenwich",0],UNIT["degree",0.0174532925199433]],PROJECTION["Lambert_Conformal_Conic_2SP"],PARAMETER["standard_parallel_1",31.8833333333333],PARAMETER["standard_parallel_2",30.1166666666667],PARAMETER["latitude_of_origin",29.6666666666667],PARAMETER["central_meridian",-100.333333333333],PARAMETER["false_easting",2296583.33333333333333],PARAMETER["false_northing",9842500],UNIT["US_Foot",0.30480060960121924]]
42308=PROJCS["NAD27 / California Albers",GEOGCS["NAD27",DATUM["North_American_Datum_1927",SPHEROID["Clarke 1866",6378206.4,294.978698213901],TOWGS84[-9,151,185]],PRIMEM["Greenwich",0],UNIT["degree",0.0174532925199433]],PROJECTION["Albers_conic_equal_area"],PARAMETER["central_meridian",-120.0],PARAMETER["latitude_of_origin",0],PARAMETER["standard_parallel_1",34],PARAMETER["standard_parallel_2",40.5],PARAMETER["false_northing",-4000000],UNIT["Meter",1]]
42309=PROJCS["NAD 83 / LCC Canada AVHRR-2",GEOGCS["NAD83",DATUM["North_American_Datum_1983",SPHEROID["GRS 1980",6378137,298.257222101],TOWGS84[0,0,0]],PRIMEM["Greenwich",0],UNIT["degree",0.0174532925199433]],PROJECTION["Lambert_Conformal_Conic_2SP"],PARAMETER["central_meridian",-95.0],PARAMETER["latitude_of_origin",0],PARAMETER["standard_parallel_1",49.0],PARAMETER["standard_parallel_2",77.0],UNIT["Meter",1]]
42310=PROJCS["WGS84+GRS80 / Mercator",GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["GRS 1980",6378137,298.257222101],TOWGS84[0,0,0]],PRIMEM["Greenwich",0],UNIT["Decimal_Degree",0.0174532925199433]],PROJECTION["Mercator_1SP"],PARAMETER["central_meridian",0],UNIT["Meter",1]]
42311=PROJCS["NAD83 / LCC Statcan",GEOGCS["NAD83",DATUM["North_American_Datum_1983",SPHEROID["GRS_1980",6378137,298.257222101],TOWGS84[0,0,0]],PRIMEM["Greenwich",0],UNIT["Decimal_Degree",0.0174532925199433]],PROJECTION["Lambert_Conformal_Conic_2SP"],PARAMETER["central_meridian",-91.866667],PARAMETER["latitude_of_origin",63.390675],PARAMETER["standard_parallel_1",49],PARAMETER["standard_parallel_2",77],PARAMETER["false_easting",6200000],PARAMETER["false_northing",3000000],UNIT["Meter",1]]
45555=PROJCS["WRF_Lambert_Conformal_Conic 2",GEOGCS["GCS_North_American_1983",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137,298.25722356300003]],PRIMEM["Greenwich",0],UNIT["Degree",0.017453292519943299]],PROJECTION["Lambert_Conformal_Conic_2SP"],PARAMETER["False_Easting",0],PARAMETER["False_Northing",0],PARAMETER["Central_Meridian",-97],PARAMETER["Standard_Parallel_1",33],PARAMETER["Standard_Parallel_2",60],PARAMETER["Latitude_Of_Origin",40.003338],UNIT["Meter",1],AUTHORITY["EPSG","45555"]]
45556=PROJCS["Albers Equal area",GEOGCS["WGS 84", DATUM["World Geodetic System 1984", SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], AUTHORITY["EPSG","6326"]], PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], UNIT["degree", 0.017453292519943295], AUTHORITY["EPSG","4326"]], PROJECTION["Albers Equal Area", AUTHORITY["EPSG","9822"]], PARAMETER["central_meridian", -96.0], PARAMETER["latitude_of_origin", 37.5], PARAMETER["standard_parallel_1", 29.833333333333336], PARAMETER["false_easting", 0.0], PARAMETER["false_northing", 0.0], PARAMETER["standard_parallel_2", 45.833333333333336], UNIT["m", 1.0], AUTHORITY["EPSG","45556"]]
54004=PROJCS["WGS84 / Simple Mercator", GEOGCS["WGS 84", DATUM["WGS_1984", SPHEROID["WGS_1984", 6378137.0, 298.257223563]], PRIMEM["Greenwich", 0.0], UNIT["degree", 0.017453292519943295]], PROJECTION["Mercator_1SP_Google"], PARAMETER["latitude_of_origin", 0.0], PARAMETER["central_meridian", 0.0], PARAMETER["scale_factor", 1.0], PARAMETER["false_easting", 0.0], PARAMETER["false_northing", 0.0], UNIT["m", 1.0], AXIS["x", EAST], AXIS["y", NORTH], AUTHORITY["EPSG","54004"]]
100001=GEOGCS["NAD83 / NFIS Seconds",DATUM["North_American_Datum_1983",SPHEROID["GRS 1980",6378137,298.257222101],TOWGS84[0,0,0]],PRIMEM["Greenwich",0],UNIT["Decimal_Second",4.84813681109536e-06]]
100002=PROJCS["NAD83 / Austin",GEOGCS["NAD83",DATUM["North_American_Datum_1983",SPHEROID["GRS 1980",6378137,298.257222101],TOWGS84[0,0,0]],PRIMEM["Greenwich",0],UNIT["degree",0.0174532925199433]],PROJECTION["Lambert_Conformal_Conic_2SP"],PARAMETER["standard_parallel_1",31.8833333333333],PARAMETER["standard_parallel_2",30.1166666666667],PARAMETER["latitude_of_origin",29.6666666666667],PARAMETER["central_meridian",-100.333333333333],PARAMETER["false_easting",2296583.333333],PARAMETER["false_northing",9842500.0000000],UNIT["Meter",1]]
100003=PROJCS["WGS84 / Google Mercator", GEOGCS["WGS 84", DATUM["World Geodetic System 1984", SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], AUTHORITY["EPSG","6326"]], PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], UNIT["degree", 0.017453292519943295], AUTHORITY["EPSG","4326"]], PROJECTION["Mercator (1SP)", AUTHORITY["EPSG","9804"]], PARAMETER["semi_major", 6378137.0], PARAMETER["semi_minor", 6378137.0], PARAMETER["latitude_of_origin", 0.0], PARAMETER["central_meridian", 0.0], PARAMETER["scale_factor", 1.0], PARAMETER["false_easting", 0.0], PARAMETER["false_northing", 0.0], UNIT["m", 1.0], AUTHORITY["EPSG","900913"]]
900913=PROJCS["WGS84 / Google Mercator", GEOGCS["WGS 84", DATUM["World Geodetic System 1984", SPHEROID["WGS 84", 6378137.0, 298.257223563, AUTHORITY["EPSG","7030"]], AUTHORITY["EPSG","6326"]], PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], UNIT["degree", 0.017453292519943295], AUTHORITY["EPSG","4326"]], PROJECTION["Mercator (1SP)", AUTHORITY["EPSG","9804"]], PARAMETER["semi_major", 6378137.0], PARAMETER["semi_minor", 6378137.0], PARAMETER["latitude_of_origin", 0.0], PARAMETER["central_meridian", 0.0], PARAMETER["scale_factor", 1.0], PARAMETER["false_easting", 0.0], PARAMETER["false_northing", 0.0], UNIT["m", 1.0],  AUTHORITY["EPSG","900913"]]
30031000=PROJCS["Monte Mario / Italy zone 1 - Peninsular Part/Accuracy 3-4m", GEOGCS["Monte Mario", DATUM["Monte Mario", SPHEROID["International 1924", 6378388.0, 297.0, AUTHORITY["EPSG","7022"]], TOWGS84[-104.1, -49.1, -9.9, 0.971, -2.917, 0.714, -11.68], AUTHORITY["EPSG","6265"]], PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], UNIT["degree", 0.017453292519943295], AXIS["Geodetic longitude", EAST], AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4265"]], PROJECTION["Transverse_Mercator"], PARAMETER["central_meridian", 9.0], PARAMETER["latitude_of_origin", 0.0], PARAMETER["scale_factor", 0.9996], PARAMETER["false_easting", 1500000.0], PARAMETER["false_northing", 0.0], UNIT["m", 1.0], AXIS["Easting", EAST], AXIS["Northing", NORTH], AUTHORITY["EPSG","30031000"]]
30031001=PROJCS["Monte Mario / Italy zone 1 - Sardinia/Accuracy 3-4m", GEOGCS["Monte Mario", DATUM["Monte Mario", SPHEROID["International 1924", 6378388.0, 297.0, AUTHORITY["EPSG","7022"]], TOWGS84[-168.6,-34.0,38.6,-0.374,-0.679,-1.379,-9.48], AUTHORITY["EPSG","6265"]], PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], UNIT["degree", 0.017453292519943295], AXIS["Geodetic longitude", EAST], AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4265"]], PROJECTION["Transverse_Mercator"], PARAMETER["central_meridian", 9.0], PARAMETER["latitude_of_origin", 0.0], PARAMETER["scale_factor", 0.9996], PARAMETER["false_easting", 1500000.0], PARAMETER["false_northing", 0.0], UNIT["m", 1.0], AXIS["Easting", EAST], AXIS["Northing", NORTH], AUTHORITY["EPSG","30031001"]]
30031002=PROJCS["Monte Mario / Italy zone 1 - Sicily/Accuracy 3-4m", GEOGCS["Monte Mario", DATUM["Monte Mario", SPHEROID["International 1924", 6378388.0, 297.0, AUTHORITY["EPSG","7022"]], TOWGS84[-50.2,-50.4,84.8,-0.690,-2.012,0.459,-28.08], AUTHORITY["EPSG","6265"]], PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], UNIT["degree", 0.017453292519943295], AXIS["Geodetic longitude", EAST], AXIS["Geodetic latitude", NORTH], AUTHORITY["EPSG","4265"]], PROJECTION["Transverse_Mercator"], PARAMETER["central_meridian", 9.0], PARAMETER["latitude_of_origin", 0.0], PARAMETER["scale_factor", 0.9996], PARAMETER["false_easting", 1500000.0], PARAMETER["false_northing", 0.0], UNIT["m", 1.0], AXIS["Easting", EAST], AXIS["Northing", NORTH], AUTHORITY["EPSG","30031002"]]
30041000=PROJCS["Monte Mario / Italy zone 2 - Peninsular Part/Accuracy 3-4m", GEOGCS["Monte Mario", DATUM["Monte_Mario", SPHEROID["International 1924", 6378388.0, 297.0, AUTHORITY["EPSG","7022"]], TOWGS84[-104.1, -49.1, -9.9, 0.971, -2.917, 0.714, -11.68], AUTHORITY["EPSG","6265"]], PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], UNIT["degree", 0.017453292519943295], AXIS["Lon", EAST], AXIS["Lat", NORTH], AUTHORITY["EPSG","4265"]], PROJECTION["Transverse_Mercator"], PARAMETER["central_meridian", 15.0], PARAMETER["latitude_of_origin", 0.0], PARAMETER["scale_factor", 0.9996], PARAMETER["false_easting", 2520000.0], PARAMETER["false_northing", 0.0], UNIT["m", 1.0], AXIS["x", EAST], AXIS["y", NORTH], AUTHORITY["EPSG","30041000"]] 
30041001=PROJCS["Monte Mario / Italy zone 2 - Sardinia/Accuracy 3-4m", GEOGCS["Monte Mario", DATUM["Monte_Mario", SPHEROID["International 1924", 6378388.0, 297.0, AUTHORITY["EPSG","7022"]], TOWGS84[-168.6,-34.0,38.6,-0.374,-0.679,-1.379,-9.48], AUTHORITY["EPSG","6265"]], PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], UNIT["degree", 0.017453292519943295], AXIS["Lon", EAST], AXIS["Lat", NORTH], AUTHORITY["EPSG","4265"]], PROJECTION["Transverse_Mercator"], PARAMETER["central_meridian", 15.0], PARAMETER["latitude_of_origin", 0.0], PARAMETER["scale_factor", 0.9996], PARAMETER["false_easting", 2520000.0], PARAMETER["false_northing", 0.0], UNIT["m", 1.0], AXIS["x", EAST], AXIS["y", NORTH], AUTHORITY["EPSG","30041001"]] 
30041002=PROJCS["Monte Mario / Italy zone 2 - Sicily/Accuracy 3-4m", GEOGCS["Monte Mario", DATUM["Monte_Mario", SPHEROID["International 1924", 6378388.0, 297.0, AUTHORITY["EPSG","7022"]], TOWGS84[-50.2,-50.4,84.8,-0.690,-2.012,0.459,-28.08], AUTHORITY["EPSG","6265"]], PRIMEM["Greenwich", 0.0, AUTHORITY["EPSG","8901"]], UNIT["degree", 0.017453292519943295], AXIS["Lon", EAST], AXIS["Lat", NORTH], AUTHORITY["EPSG","4265"]], PROJECTION["Transverse_Mercator"], PARAMETER["central_meridian", 15.0], PARAMETER["latitude_of_origin", 0.0], PARAMETER["scale_factor", 0.9996], PARAMETER["false_easting", 2520000.0], PARAMETER["false_northing", 0.0], UNIT["m", 1.0], AXIS["x", EAST], AXIS["y", NORTH], AUTHORITY["EPSG","30041002"]]

Coverage FAQ

Q: Relationship with ISO Coverage?

Within GeoTools, the coverage module exists below the main module (where Feature is defined) and therefore a GeoTools GridCoverage is not a feature.

This is in opposition to the ISO Coverage model (where Coverage extends Feature) provided by ISO 19123 specification.

GeoTools ‘Coverage’ objects emerged from an earlier specification published by the OpenGeospatial Consortium (OGC) called “Grid Coverage Services Implementation” (OGC 01-004).

Q: How is raster data supported?

The design of the coverage modules follows closely the design of image handling in Java. Java provides three major subsystems in their Java media API’s which are used and extended in GeoTools.

Image I/O system
To access files with image content. This provides code to access many standard image formats.
Java Advanced Imaging (JAI) system
which provides a powerful approach for performing operations on images. Not only does JAI provide efficient code for performing lots of operations, but it creates a system through which a user can create chains of operations which can be applied repeatedly to an image or applied to a whole slew of images.
JAI Image I/O system
Combines the two other systems by treating image access as one of the JAI operations allowing for differed access and enabling the treatment of file access as a standard step in an operation chain. The module also provides access to additional file formats.

When combined, these subsystems provide immense power to the GeoTools coverage module but this dependency does require that programmers who wish to use and extend the module must learn to use these other Java modules.

To get the most out of the gt-coverage module developers should be familiar with the underlying mathematical ideas. Knowledge of ideas such as an Affine Transforms (for rotating and scaling) is required to work effectively with the coverage module. Affines are explained any computer graphics textbooks, and on many web sites, if you need a refresher.

Main FAQ

Q: What is gt-main responsible for?

The gt-main module is responsible for the default implementations of the formal interfaces provided by gt-api and gt-opengis. This includes the default implementations for the feature model, filter support, and style definition.

The gt-main module makes this functionality available through the plug-in system allowing you to make use of CommonFactoryFinder rather than directly depend on the default implementations provided here.

Q: How do I make a FeatureType?

You can make a feature type quickly using using the DataUtilities class:

SimpleFeatureType lineType = DataUtilities.createType(“LINE”, “centerline:LineString,name:””,id:0”);

For greater control consider direct use of a FeatureTypeBuilder:

SimpleFeatureTypeBuilder b = new SimpleFeatureTypeBuilder();

//set the name
b.setName( "Flag" );

//add some properties
b.add( "name", String.class );
b.add( "classification", Integer.class );
b.add( "height", Double.class );

//add a geometry property
b.setCRS( DefaultGeographicCRS.WSG84 ); // set crs first
b.add( "location", Point.class ); // then add geometry

//build the type
final SimpleFeatureType FLAG = b.buildFeatureType();

Q: How do I modify a FeatureType?

You cannot modify a feature type directly as it is considered immutable and not subject to change.

You can however use a FeatureTypeBuilder to create a modified copy:

SimpleFeatureType lineType = DataUtilities.createType("LINE", "geom:LineString,name:\"\",id:0");
SimpleFeatureTypeBuilder b = new SimpleFeatureTypeBuilder();
b.init( lineType );
b.setName("POINT");
b.add(0, "geom", Point.class );
SimpleFeatureType pointType = b.buildFeatureType();

Q: How to get FeatureCollection to work with a ‘for each’ loop?

Feature collection is a wrapper around a live data stream; as such we need to be sure to close the iterator after we are through with it:

    SimpleFeatureIterator iterator = featureCollection.features();
    try {
        while( iterator.hasNext() ){
            SimpleFeature feature = iterator.next();
            // process feature
        }
    }
    finally {
        iterator.close();
    }

This requirement prevents us implementing Collection (and being compatible with ‘for each’ syntax. I am afraid this is a fundamental limitation of Java and not something that can or should be addressed in a future release.

JDBC FAQ

Q: How to access a database from Java Enterprise Edition?

Depending on your application container (and organisational polices) you may be restricted to only using database connection pools under control of your administrator.

Your administrator will register the database connection pool with the application server and configure your application with the Java Naming and Directory Interface (JNDI) reference.

To use GeoTools with a JNDI name:

Map map = new HashMap();
map.put( "dbtype", "postgis");
map.put( "jndiReferenceName", "java:comp/env/jdbc/geotools");

DataStore store =  DataStoreFinder.getDataStore(map);

The specific “dbtype” marks the plugin you will use to communicate with the database.

CQL FAQ

Q: What is CQL used for?

The CQL utility class has static methods to parse an input String into either a Filter or an Expression.

Here is the most common use for the CQL class - asking for Features:

        Filter filter = CQL.toFilter("population >= 10000000");

The CQL utility class produced is a Filter; you can create Filters by hand (using a FilterFactory) but this is much easier.

Q: What version of CQL is implemented?

The input string defining the query predicate that CQL accepts has to respond to the grammar of the OGC Common Query Language, defined in the Catalog Service for Web, v2.0.1, from the OGC.

We’ve added a couple extensions and fixes to that grammar in order to fix a bug in the definition of temporal expressions and to leverage its use in the GeoTools library.

Q: Can I just try CQL out?

If you’re developing with GeoTools, you can easily try out the CQL parser by depending on the gt-cql jar and running the CQL class as a normal Java application.

It will present a prompt on the console (standard input) from where you can input cql strings and will get back the corresponding Filter in xml encoding.:

Expression Tester ("quit" to finish)
>attr > 10
<?xml version="1.0" encoding="UTF-8"?>
<ogc:PropertyIsGreaterThan xmlns="http://www.opengis.net/ogc"
                           xmlns:ogc="http://www.opengis.net/ogc"
                           xmlns:gml="http://www.opengis.net/gml">
  <ogc:PropertyName>attr</ogc:PropertyName>
  <ogc:Literal>10</ogc:Literal>
</ogc:PropertyIsGreaterThan>

>quit
Bye!

Q: What does ECQL offer?

The ECQL class offers an extension of the basic CQL language, it is backward compatable so the following still works:

        Filter filter = ECQL.toFilter("POPULTATION >= 1000");

The ECQL has a syntax more flexible and nearest to the natural language. By example, ECQL allows to use an expression in the left hand of comparison as is showed in the following example

XML FAQ

Q: What parser does GeoTools use?

We have a range of tools to help you with parsing and encoding XML. As a general purpose library GeoTools does not have the luxury of choosing a parser to work with.

The following parsers are based on W3C APIs (SAX, DOM, and XML Transform). You can choose the most appropriate solution for the system you want to use GeoTools in.

Technology SAX DOM Encode Support Notes
SAX sax dom   Filter GML SLD Hard to trace through, parse not easily extended
DOM   dom   Filter GML SLD Forgiving and easy to trace through and debug, memory limitation for GIS data
Transform     XML Filter GML2 SLD Easy to trace through and debug, difficult to configure for specific data
JABX sax dom XML n/a Fast but not suitable for dynamic data, precomplied
Pull sax dom   n/a Should combine the ease of DOM with the streaming performance of XDO and GTXML
XDO sax dom XML Filter GML SLD WMS WFS1.0 XSD Proof of concept of schema assisted parsing allowing streaming into Java Objects. Code is fast and well tested but is hard to trace through
GTXML sax dom XML Filter GML SLD WMS WFS1.0 WFS1.1 WPS XSD

Schema assisted parsing backed by Eclipse XSD to represent schema.

Easier to trace through but still not straight forward

Allows streaming for large GIS data volumes.

The XDO and GTXML solutions are configuration based. You set up a configuration matching the data you wish to work with and the technology will make use of any XML schema available to assist in parsing or encoding your content correctly.

The JAXB library from Java is a little different in that you start from an XML schema and generate a parser or encoder class for use. This solution performs well but cannot be used for dynamic content such as GML.

Q: What is SAX?

SAX is a W3C technology from the early days of XML. SAX Parsers work using callbacks, they pass control between several hard coded implementations. For basic use you create your own SAX Parser (say responding to a new Geometry being parsed) and pass control off to the GeoTools implementations and wait for it to call you.

  • Allows streaming for large content.
  • Rather tricky to set up
  • Reuse of a SAX parser is possible, but is very tricky to reuse

As a result SAX parsers are rather “brittle” and difficult to maintain are currently hardcoded to pass control between themselves, making support for new specifications tricky.

Example: while parsing a Filter control will be need to be handed over to a Geometry parser if the expression contains a literal Geometry.

The later Schema Assisted parsers are an attempt to let mere mortals create a tree of handlers on the fly (they use the schema document to do a bunch of the grunt work) that is hard coded for the SAX Parsers.

Q: What is DOM?

The W3C Document Object Model (DOM) is most popularly used to represent the the contents of a web page as a series of Nodes. These notes form a tree structure and can be used to represent the contents of an XML document in memory.

As a result the GeoTools DOM parsers are functions that can wander through an in memory DOM doing their best to extract content.

Delegation is hard coded in much the same way as with the SAX parsers.

  • accessible easy to understand technology
  • very nice for quick examples
  • obvious how to use the parser
  • solution does not scale to large content as steaming not available
  • can only handle direct use of GML
  • additional coding is always required to parse your own content

Q: What is XML Transform?

Traditional XML generation, traverse your data structure and call methods to generate as you go.

  • very fast, so fast we use it for GeoServer even though it is hard to maintain
  • scalable (does not load features into memory)
  • not open ended
  • need to carefully provide hints before use
  • may revisit data several times (for bounding box and then content)

Q: Schema Assisted -did you make that up?

Yes we did.

This idea of “Schema Assisted” parsers is a GeoTools specific piece of technology. Then general idea is to makes use of XML Schema information to minimise the amount of code you need to write.

A parser is supplied a configuration of bindings; each binding maps an XML elements or XML attributes to Java class.

While this sounds similar to other XML parsing technologies we do have a couple of key differences:

  • taking special care to pay attention to the schema at runtime (so we can parse new documents using the “best” binding available rather than fail)
  • Ensure that data is not loaded into memory; allowing us to “stream” the XML document through an application.
  • We are on our third generation schema assisted parser.

Q: XDO?

XML Data Objects (XDO) is the third generation of our schema assisted parser idea (where the SAX bindings are referenced by the XMLSchema rather then directly hard coded). This is fast scalable solution that supports reading and writing.

  • fast and proven solution for geospatial data
  • ability to handle MASSIVE content like FeatureCollections
  • how to create new bindings is not obvious

Q: GTXML?

GeoTools XML (GTXML) is the forth generation schema assisted parser, using the XML Schema data structure (rather then hard coding) to figure out what binding to call. The XSD is used to hold our representation of the schema at runtime.

  • schema aware allowing use of new content without additional coding
  • code generator for making custom bindings
  • streaming content for MASSIVE content like feature collections
  • support for content generation
  • hard to debug and trace through the parsing or encoding process
  • code generator available to jump start the development of bindings
  • examples how how to use Eclipse Modeling Objects (EMF) based bindings to work directly from the schema

Q: Why doesn’t GeoTools use JAXB?

JAXB is a set of Java technologies (now included as part of Java 6) that are able to generate a parser form an XML schema.

A couple of groups have used JAXB have bind things such as OGC Filter. In general works well; however it does have trouble responding to content that is negotiated dynamically ... such as GML.

Q: For WFS why does Parser return a Map?

This shows up as the following error:

  • ClassCastException “java.util.HashMap cannot be cast to FeatureCollection”.

To understand this error please remember that the GML returned by a WFS GetFeatures request is a normal XML file, with a reference to an XML schema at the top.

For a WFS GetFeature response the schema reference is usually a DescribeFeatureType call that returns an XML Schema.

If this schema is incorrectly configured (common with MapServer) or cannot be reached (common with restricted environments) our Parser will give up guessing what is a Feature and just return the values in a HashMap.

Note

If you are using the GML utility class it will perform a bit of analysis and create an ad-hoc FeatureType in order to return you Features.

  • looking at the HashMaps returned
  • building a feature type that matches that kind of contents
  • building features that match that FeatureType

This is similar to the approach taken by OGR; OGR figures out where the “geometry” is; and then goes up two levels and assumes those things are features.

Both of these approaches are strictly a work around for a common problem of misconfigured WFS servers.

Here is how to review the configuration of your WFS Server:

  1. If you are having a problem with a HashMap being returned when you expect a Feature, you should check GetCapabilities responses for remote server e.g. with browser:

    http://{URL}?SERVICE=WFS&VERSION=1.1.0&REQUEST=GetCapabilities
  2. After that, ensure that <ows:Operation> elements contain urls that actually work

  3. In particular check that DescribeFeatureType responds with the expected XML Schema

Q: I am in a restricted environment, how to configure SchemaLocator?

You can configure the Parser with a SchemaLocator (we use this internally to force the parser to a copy of the GML schema included in the GeoTools jars; rather than force the Parser to download the GML schema each time).

  1. To customise how XML Schemas are located in a restricted environment (such as web portal for multiple WFS services that require authorization, or require the use of an HTTP proxy for schema requests).

  2. Create custom SchemaLocator we start with configuration like so:

    GMLConfiguration configuration = new GMLConfiguration() {
        public void configureContext(final MutablePicoContainer container) {
            super.configureContext(container);
            String username = "geotools user";
            String password = "support osgeo";
            Boolean useProxy = true;
            XSDSchemaLocator locator = new CachingSchemaLocator(username, password, useProxy);
            QName key = new QName("mycustom", "schemaLocator");
            container.registerComponentInstance(key, locator);
        }
    };
  3. In the above code, CachingSchemaLocator is a custom XSDSchemaLocator:

    public class CachingSchemaLocator implements XSDSchemaLocator {
        public XSDSchema locateSchema(XSDSchema schema, String namespaceURI, String rawSchemaLocationURI, String resolvedSchemaLocationURI) {
    
             ... Implementation ...
    
        }
    }
  4. Set up a configuration for use with the Parser:

    Parser parser = new Parser(configuration);
    
    parser.setValidating(false);
    parser.setFailOnValidationError(false);
    parser.setStrict(false);
    FeatureCollection<SimpleFeatureType, SimpleFeature> features = parser.parse(... WFS response InputStream Here ...);

Render FAQ

How do I display a shapefile?

Have a look at Tutorials which provides a quickstart showing how to do this.

Q: What is SLD?

Style Layer Descriptor Specification (SLD) is an OGC standard defining styles used when drawing maps. Think of it as CSS for maps.

GeoTools rendering is based around the Style Layer Descriptor standard, for details please see the gt-opengis module.

This standard is divided into two parts:

  • Style Layer Descriptor 1.1 covers the integration of styles with a web map server.
  • Symbology Encoding 1.1 covers the definition of a feature type style controlling how a rendering engine draws features.

Q: What is a MapContent?

A MapContent object holds one or more Layers which are rendered in the order that they were added.

This is not part of the formal gt-opengis module because it is not considered finished, done, or complete. The GeoTools community is actively looking to collaborate with other projects (such as OpenJUMP, uDig and deegree) in order to collaborate on these ideas. If open source collaboration fails we will look to traditional collaboration with a standards body in the form of the the OGC working group on “Open Web Context” documents.

Q: What about the Widget?

This module only draws into a Graphics2D context (so printer or image buffer). You can use this functionality in your own Swing widget in order to draw something on screen.

  • gt-swing

    GeoTools does not provide comprehensive GUI components but there is a basic Swing widget JMapFrame in the gt-swing module which is used in GeoTools example code. This can be used directly in your applications or it could form the starting point for writing your own Swing components. See JMapFrame for more details.

  • gt-swt

    The gt-swing JMapFrame has been ported to an SWT widget as an unsupported module.

  • udig

    uDig is an application and SDK built around the Eclipse platform, please consider this a real world solution suitable for desktop applications. It makes use of the SWT toolkit so while you can use it as an example of how to do really fast rendering you will not be able to directly use the code in a swing application.

Brewer FAQ

Q: I have 47 classes to represent and ColorBrewer only goes up to 12!

Feel free to create your own Color[] for use with StyleGenerator.

Q: But why does it only go up to 12?

This is a surprisingly common question!

Have a look at the http://colorbrewer2.org/ website above; the point of the research is that the human eye cannot tell very many colours apart. Indeed the number goes down depending on what you are trying communicate (ie that the things shown are of equal importance, or do they form a smooth spread of values?).

In other words you are free to create a pretty map with more than 12 colours; but you should not be surprised if that is too complicated for people to understand.

WMS FAQ

Q: Scrambled PNG Images?

A couple versions of Java ship with broken native PNG support (gasp!). If you find your WMS image scrambled you can try the following:

ImageUtilities.allowNativeCodec("png", ImageReaderSpi.class, false);

This code fragments disables the native PNG reader (the pure java one is fine; and in some platforms faster).

Swing FAQ

Q: What is JMapPane for?

The JMapPane class is primiarly used as a teaching aid for the tutorials used to explore the GeoTools library.

It is developed in collaboration with the user list, and while not a intended as a GIS application it is a good starting point for trying out your ideas.

Q: What is the best way to simulate a car moving on a map?

There is a flying saucers demo you can review; but the real answer is to set up a second raster to draw your moving car into; and draw that over top of the map rendered by gt-renderer.

Remember that JMapPane is just a demo showing how you can use StreamingRenderer to draw into a BufferedImage. You can do the same thing in your own code; and have one buffered image for the map and a second one for your “overlays” including the moving car.

Q: JMapPane is Slow how do I make it faster?

This really comes down to how you use the GeoTools renderer. Remember that the GeoTools renderer is doing a lot of calculation and data access; not what you want in the middle of animation.

The gt-renderer is optimised for memory use; it does not loading your data into memory (it is drawing from disk, or database, each time). You can experiment with loading your data into memory (specifically into a spatial index) if you want faster performance out of it.

For raster rendering you have a great deal of control over performance using JAI TileCache settings in addition to convering your rasters into an efficient format (anything is better than jpeg).

Referneces:

Building FAQ

What version of JDK?

Our policy is waiting for the majority of our users before migrating to a new version of the Java language. In general we are held up by the slow migration of Java Enterprise Edition environments such as websphere.

GeoTools 8 uses Java 6.

How do I build from source code?

Complete build instructions are provided in the user guide:

GeoTools makes use of the maven build system (in part to help us reused code from a number of other java projects).

To build all the modules:

mvn install -Dall

To load the modules into the eclipse IDE.

  1. Use Windows ‣ Preferences to open the Preference Dialog. Using the tree on the left navigate to the Java > Build path > Classpath Variables preference Page.

  2. Add an M2_REPO classpath variable pointing to your local repository where maven downloads jars.

    PLATFORM LOCAL REPOSITORY
    Windows XP: C:\Documents and Settings\Jody\.m2\repository
    Windows: C:\Users\Jody.m2\repository
    Linux and Mac: ~/.m2/repository
  1. Generate the .project and .classpath files needed for eclipse:

    mvn eclipse:eclipse -Dall
  1. You can now use the eclipse import wizard to load existing projects.

Why is Maven 3 Slower?

Maven 3 is not faster out of the box with the default settings.

Gowever what is new is that you can ask it to use more than one core:

mvn install -Dall -T 2C

The above asks the build to go in “threaded” mode; using two threads for each core.

What the fastest build?

This is the fastest build on my machine:

mvn install -DskipTests -o -T 2C

The above options:

  • install (without clean) only recompiles modified code
  • no profiles or flags are used to build optional code; onlt the core library is built
  • skipTests - the tests are still built; they are just not run
  • o - allows the build to work “offline” (thus no external servers are checked during the build)
  • T 2C - builds with two threads per core

I use this configuration to quickly push all local changes into my local maven repository so I can test in a downstream application such as uDig or GeoServer.

How do I create an executable jar for my GeoTools app?

If you’re familiar with Maven you might have used the assembly plugin to create self-contained, executable jars. The bad news is that this generally won’t work with GeoTools. The problem is that GeoTools modules often define one or more files in its META-INF/services directory with the same names as files defined in other modules. The assembly plugin just copies files with the same name over the top of each other rather than merging their contents.

The good news is that the Maven shade plugin can be used instead and it will correctly merge the META-INF/services files from each of the GeoTools modules used by your application.

The POM below will create an executable jar for the GeoTools Quickstart module which includes all of the required GeoTools modules and their dependencies.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.geotools.demo</groupId>
  <artifactId>quickstart</artifactId>
  <packaging>jar</packaging>
  <version>1.0</version>
  <name>GeoTools Quickstart example</name>
  <url>http://geotools.org</url>

  <properties>
      <geotools.version>2.6.2</geotools.version>
  </properties>

  <build>
      <plugins>
          <plugin>
              <artifactId>maven-compiler-plugin</artifactId>
              <configuration>
                  <encoding>UTF-8</encoding>
                  <target>1.5</target>
                  <source>1.5</source>
              </configuration>
          </plugin>
          <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-shade-plugin</artifactId>
              <version>1.3.1</version>
              <executions>
                  <execution>
                      <phase>package</phase>
                      <goals>
                          <goal>shade</goal>
                      </goals>
                      <configuration>
                          <transformers>
                              <!-- This bit sets the main class for the executable jar as you otherwise -->
                              <!-- would with the assembly plugin                                       -->
                              <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                                  <manifestEntries>
                                      <Main-Class>org.geotools.demo.Quickstart</Main-Class>
                                  </manifestEntries>
                              </transformer>
                              <!-- This bit merges the various GeoTools META-INF/services files         -->
                              <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                          </transformers>
                      </configuration>
                  </execution>
              </executions>
          </plugin>
      </plugins>
  </build>

  <dependencies>
      <dependency>
          <groupId>org.geotools</groupId>
          <artifactId>gt-shapefile</artifactId>
          <version>${geotools.version}</version>
      </dependency>
      <dependency>
          <groupId>org.geotools</groupId>
          <artifactId>gt-epsg-hsql</artifactId>
          <version>${geotools.version}</version>
      </dependency>
      <dependency>
          <groupId>org.geotools</groupId>
          <artifactId>gt-swing</artifactId>
          <version>${geotools.version}</version>
      </dependency>
      <dependency>
          <groupId>junit</groupId>
          <artifactId>junit</artifactId>
          <version>4.5</version>
          <scope>test</scope>
      </dependency>
  </dependencies>
</project>