Project URL: https://github.com/geotools/geotools
Maven GroupId:
org.geotoolsLicense: LGPL 2.1
Documentation link: https://docs.geotools.org/
Overview
GeoTools is a mature, modular open-source Java GIS library managed by the OSGeo Foundation and widely used in well-known GIS platforms such as GeoServer and uDig. It provides:
- Vector data access: Shapefile, GeoPackage, GeoJSON, PostGIS, Oracle Spatial, SQL Server, etc.
- Raster data access: GeoTIFF, NetCDF, ImageMosaic, etc.
- Coordinate Reference System (CRS): Projection definitions and coordinate transformations based on the EPSG database
- Spatial query and filtering: CQL / ECQL, OGC Filter encoding
- Map rendering: SLD/SE-based cartographic styling and image output
- OGC Web services: WMS / WFS / WCS clients
- Geometry operations: A full set of geometric computations based on the JTS Topology Suite
Environment requirements: JDK 11+(GeoTools 21–33);JDK 17+(GeoTools 34+)
Quick integration
Maven repository configuration
GeoTools is published in the OSGeo Maven repository, and you need to add the following to pom.xml :
<repositories>
<repository>
<id>osgeo</id>
<name>OSGeo Release Repository</name>
<url>https://repo.osgeo.org/repository/release/</url>
</repository>
</repositories>
Common module dependencies
<properties>
<geotools.version>32.1</geotools.version>
</properties>
<dependencies>
<!-- 核心 -->
<dependency>
<groupId>org.geotools</groupId>
<artifactId>gt-main</artifactId>
<version>${geotools.version}</version>
</dependency>
<!-- Shapefile -->
<dependency>
<groupId>org.geotools</groupId>
<artifactId>gt-shapefile</artifactId>
<version>${geotools.version}</version>
</dependency>
<!-- GeoTIFF 栅格 -->
<dependency>
<groupId>org.geotools</groupId>
<artifactId>gt-geotiff</artifactId>
<version>${geotools.version}</version>
</dependency>
<!-- GeoPackage -->
<dependency>
<groupId>org.geotools</groupId>
<artifactId>gt-geopkg</artifactId>
<version>${geotools.version}</version>
</dependency>
<!-- EPSG 坐标系数据库(HSQL 嵌入式) -->
<dependency>
<groupId>org.geotools</groupId>
<artifactId>gt-epsg-hsql</artifactId>
<version>${geotools.version}</version>
</dependency>
<!-- PostGIS -->
<dependency>
<groupId>org.geotools.jdbc</groupId>
<artifactId>gt-jdbc-postgis</artifactId>
<version>${geotools.version}</version>
</dependency>
<!-- CQL 查询语言 -->
<dependency>
<groupId>org.geotools</groupId>
<artifactId>gt-cql</artifactId>
<version>${geotools.version}</version>
</dependency>
<!-- 地图渲染 -->
<dependency>
<groupId>org.geotools</groupId>
<artifactId>gt-render</artifactId>
<version>${geotools.version}</version>
</dependency>
<!-- GeoJSON 数据格式 -->
<dependency>
<groupId>org.geotools</groupId>
<artifactId>gt-geojson-core</artifactId>
<version>${geotools.version}</version>
</dependency>
</dependencies>
Core modules at a glance
| Module | artifactId | Purpose |
|---|---|---|
| gt-main | gt-main |
★ Core interfaces and implementations—Feature / DataStore / Filter |
| gt-api | gt-api |
High-level API interface definitions (Feature, CRS, Filter, etc.) |
| gt-referencing | gt-referencing |
Coordinate reference system definition and transformation |
| gt-epsg-hsql | gt-epsg-hsql |
Embedded EPSG database (based on HSQL) |
| gt-shapefile | gt-shapefile |
Shapefile vector read/write |
| gt-geopkg | gt-geopkg |
GeoPackage vector / raster read/write |
| gt-geotiff | gt-geotiff |
GeoTIFF raster read/write |
| gt-coverage | gt-coverage |
Raster coverage (GridCoverage) processing |
| gt-cql | gt-cql |
CQL / ECQL query language parsing |
| gt-render | gt-render |
Map rendering output (PNG, SVG, etc.) |
| gt-jdbc-postgis | gt-jdbc-postgis |
PostGIS database connection |
| gt-geojson-core | gt-geojson-core |
GeoJSON read/write |
| gt-wms | gt-wms |
OGC WMS client |
| gt-wfs-ng | gt-wfs-ng |
OGC WFS client |
| gt-process | gt-process |
Geoprocessing framework |
Core classes at a glance
| Class / Interface | Package | Purpose |
|---|---|---|
DataStore |
org.geotools.data |
★ Unified abstraction entry point for vector data sources |
DataStoreFinder |
org.geotools.data |
Automatically locate and create a DataStore through parameters |
FileDataStoreFinder |
org.geotools.data |
Quickly open single-file data sources (Shapefile, etc.) |
SimpleFeatureType |
org.opengis.feature.simple |
Feature type definition (field names, types, CRS) |
SimpleFeature |
org.opengis.feature.simple |
A single vector feature (attributes + geometry) |
SimpleFeatureSource |
org.geotools.data.simple |
Read-only feature data source |
SimpleFeatureStore |
org.geotools.data.simple |
Read-write feature data source |
SimpleFeatureCollection |
org.geotools.data.simple |
Feature collection |
SimpleFeatureBuilder |
org.geotools.feature.simple |
Build SimpleFeature instances |
SimpleFeatureTypeBuilder |
org.geotools.feature.simple |
Build SimpleFeatureType definitions |
Geometry |
org.locationtech.jts.geom |
JTS geometry base classes (Point, LineString, Polygon, etc.) |
GeometryFactory |
org.locationtech.jts.geom |
Factory for creating geometry objects |
JTSFactoryFinder |
org.geotools.geometry.jts |
The GeoTools-recommended way to obtain a GeometryFactory |
JTS |
org.geotools.geometry.jts |
JTS geometry utility classes (coordinate transformation, Envelope conversion, etc.) |
CRS |
org.geotools.referencing.CRS |
★ Coordinate reference system utility class (decode EPSG, find transformations) |
CoordinateReferenceSystem |
org.opengis.referencing.crs |
CRS interfaces |
MathTransform |
org.opengis.referencing.operation |
Coordinate transformation mathematical transformations |
Filter |
org.opengis.filter |
OGC filter interfaces |
CQL |
org.geotools.filter.text.cql2 |
CQL query language parser |
ECQL |
org.geotools.filter.text.ecql |
Extended CQL parser (supports more syntax) |
Style |
org.geotools.styling |
SLD cartographic styles |
SLD |
org.geotools.styling.SLD |
Utility classes for quickly creating simple styles |
MapContent |
org.geotools.map |
Map container (manages layer collections) |
FeatureLayer |
org.geotools.map |
Vector layer |
GridCoverage2D |
org.geotools.coverage.grid |
2D raster coverage data |
GeoTiffReader |
org.geotools.gce.geotiff |
GeoTIFF reader |
GeoTiffWriter |
org.geotools.gce.geotiff |
GeoTIFF writer |
ReferencedEnvelope |
org.geotools.geometry.jts |
Rectangular extent with CRS |
DataUtilities |
org.geotools.data |
Data utility classes (type creation, collection conversion, etc.) |
Vector data reading
Read Shapefile
import org.geotools.data.*;
import org.geotools.data.simple.*;
import org.opengis.feature.simple.SimpleFeature;
File file = new File("data/cities.shp");
FileDataStore store = FileDataStoreFinder.getDataStore(file);
SimpleFeatureSource source = store.getFeatureSource();
SimpleFeatureCollection features = source.getFeatures();
try (SimpleFeatureIterator iter = features.features()) {
while (iter.hasNext()) {
SimpleFeature f = iter.next();
System.out.println(f.getID() + " " + f.getAttribute("NAME"));
}
}
store.dispose();
Read GeoPackage
Map<String, Object> params = new HashMap<>();
params.put("dbtype", "geopkg");
params.put("database", new File("data/world.gpkg").getAbsolutePath());
DataStore store = DataStoreFinder.getDataStore(params);
String[] typeNames = store.getTypeNames(); // 列出所有图层
SimpleFeatureSource source = store.getFeatureSource(typeNames[0]);
SimpleFeatureCollection features = source.getFeatures();
// 遍历同 Shapefile
store.dispose();
Connect to PostGIS
Map<String, Object> params = new HashMap<>();
params.put("dbtype", "postgis");
params.put("host", "localhost");
params.put("port", 5432);
params.put("schema", "public");
params.put("database", "gisdb");
params.put("user", "postgres");
params.put("passwd", "password");
DataStore store = DataStoreFinder.getDataStore(params);
SimpleFeatureSource source = store.getFeatureSource("buildings");
SimpleFeatureCollection features = source.getFeatures();
// 遍历处理...
store.dispose();
Vector data writing
Create FeatureType and write to Shapefile
import org.geotools.feature.simple.*;
import org.geotools.data.shapefile.*;
import org.locationtech.jts.geom.Point;
import org.geotools.referencing.crs.DefaultGeographicCRS;
// 1. 定义 FeatureType
SimpleFeatureTypeBuilder typeBuilder = new SimpleFeatureTypeBuilder();
typeBuilder.setName("POI");
typeBuilder.setCRS(DefaultGeographicCRS.WGS84);
typeBuilder.add("the_geom", Point.class);
typeBuilder.add("name", String.class);
typeBuilder.add("population", Integer.class);
SimpleFeatureType featureType = typeBuilder.buildFeatureType();
// 2. 构建要素
GeometryFactory gf = JTSFactoryFinder.getGeometryFactory();
SimpleFeatureBuilder fb = new SimpleFeatureBuilder(featureType);
fb.add(gf.createPoint(new Coordinate(116.4, 39.9)));
fb.add("北京");
fb.add(21540000);
SimpleFeature feature = fb.buildFeature(null);
// 3. 写入 Shapefile
ShapefileDataStoreFactory factory = new ShapefileDataStoreFactory();
Map<String, Object> params = new HashMap<>();
params.put("url", new File("output/poi.shp").toURI().toURL());
ShapefileDataStore dataStore = (ShapefileDataStore) factory.createNewDataStore(params);
dataStore.createSchema(featureType);
SimpleFeatureStore featureStore =
(SimpleFeatureStore) dataStore.getFeatureSource(dataStore.getTypeNames()[0]);
featureStore.addFeatures(DataUtilities.collection(feature));
dataStore.dispose();
Coordinate Reference System (CRS) and coordinate transformation
import org.geotools.referencing.CRS;
import org.geotools.geometry.jts.JTS;
import org.opengis.referencing.crs.CoordinateReferenceSystem;
import org.opengis.referencing.operation.MathTransform;
// 解码 EPSG
CoordinateReferenceSystem wgs84 = CRS.decode("EPSG:4326");
CoordinateReferenceSystem webMercator = CRS.decode("EPSG:3857");
CoordinateReferenceSystem cgcs2000 = CRS.decode("EPSG:4490");
// 查找坐标转换
MathTransform transform = CRS.findMathTransform(wgs84, webMercator, true);
// 转换几何对象
Geometry projected = JTS.transform(originalGeometry, transform);
// 转换单个坐标
Coordinate source = new Coordinate(116.4, 39.9);
Coordinate target = JTS.transform(source, null, transform);
// 获取 CRS 的 EPSG 编码
Integer code = CRS.lookupEpsgCode(wgs84, false);
// 从 WKT 创建 CRS
CoordinateReferenceSystem custom = CRS.parseWKT("GEOGCS[...]");
Spatial query and filtering (CQL / ECQL)
import org.geotools.filter.text.cql2.CQL;
import org.geotools.filter.text.ecql.ECQL;
import org.opengis.filter.Filter;
// 属性过滤
Filter nameFilter = CQL.toFilter("NAME = '北京'");
Filter popFilter = CQL.toFilter("POPULATION > 1000000");
// 空间过滤(BBOX)
Filter bboxFilter = CQL.toFilter(
"BBOX(the_geom, 116.0, 39.0, 117.0, 40.0)"
);
// 空间关系
Filter containsFilter = CQL.toFilter(
"CONTAINS(the_geom, POINT(116.4 39.9))"
);
Filter intersectsFilter = CQL.toFilter(
"INTERSECTS(the_geom, POLYGON((116 39, 117 39, 117 40, 116 40, 116 39)))"
);
// 组合过滤(ECQL 支持更丰富语法)
Filter combined = ECQL.toFilter(
"NAME LIKE '北%' AND POPULATION > 500000"
);
// 应用过滤查询
SimpleFeatureCollection filtered = featureSource.getFeatures(nameFilter);
Geometry operations (based on JTS)
import org.locationtech.jts.geom.*;
import org.geotools.geometry.jts.JTSFactoryFinder;
GeometryFactory gf = JTSFactoryFinder.getGeometryFactory();
// 创建几何对象
Point point = gf.createPoint(new Coordinate(116.4, 39.9));
LineString line = gf.createLineString(new Coordinate[]{
new Coordinate(0, 0), new Coordinate(10, 10), new Coordinate(20, 0)
});
Polygon polygon = gf.createPolygon(new Coordinate[]{
new Coordinate(0, 0), new Coordinate(10, 0),
new Coordinate(10, 10), new Coordinate(0, 10),
new Coordinate(0, 0) // 闭合
});
// 缓冲区
Geometry buffered = point.buffer(0.01);
// 空间关系
boolean contains = polygon.contains(point);
boolean intersects = line.intersects(polygon);
boolean within = point.within(polygon);
// 集合运算
Geometry union = polygon1.union(polygon2);
Geometry intersection = polygon1.intersection(polygon2);
Geometry difference = polygon1.difference(polygon2);
Geometry symDiff = polygon1.symDifference(polygon2);
// 几何属性
double area = polygon.getArea();
double length = line.getLength();
Point centroid = polygon.getCentroid();
Envelope env = polygon.getEnvelopeInternal();
double distance = point.distance(line);
// 凸包
Geometry convexHull = geometry.convexHull();
// 简化
import org.locationtech.jts.simplify.TopologyPreservingSimplifier;
Geometry simplified = TopologyPreservingSimplifier.simplify(geometry, 0.001);
// WKT 读写
import org.locationtech.jts.io.WKTReader;
import org.locationtech.jts.io.WKTWriter;
WKTReader wktReader = new WKTReader();
Geometry geom = wktReader.read("POINT (116.4 39.9)");
String wkt = new WKTWriter().write(geom);
Raster data (GeoTIFF)
Read GeoTIFF
import org.geotools.gce.geotiff.GeoTiffReader;
import org.geotools.coverage.grid.GridCoverage2D;
File file = new File("data/dem.tif");
GeoTiffReader reader = new GeoTiffReader(file);
GridCoverage2D coverage = reader.read(null);
// 获取 CRS
CoordinateReferenceSystem crs = coverage.getCoordinateReferenceSystem();
// 获取范围
ReferencedEnvelope envelope = new ReferencedEnvelope(coverage.getEnvelope());
// 获取像素值
double[] values = coverage.evaluate(
new DirectPosition2D(crs, 116.4, 39.9), (double[]) null
);
// 获取栅格图像
RenderedImage image = coverage.getRenderedImage();
reader.dispose();
Write GeoTIFF
import org.geotools.gce.geotiff.GeoTiffWriter;
File output = new File("output/result.tif");
GeoTiffWriter writer = new GeoTiffWriter(output);
writer.write(coverage, null);
writer.dispose();
Map rendering
Render as PNG image
import org.geotools.map.*;
import org.geotools.styling.*;
import org.geotools.renderer.lite.StreamingRenderer;
import java.awt.image.BufferedImage;
import java.awt.*;
// 创建地图
MapContent map = new MapContent();
map.setTitle("城市分布图");
// 添加矢量图层
Style style = SLD.createSimpleStyle(featureSource.getSchema());
map.addLayer(new FeatureLayer(featureSource, style));
// 渲染为图片
int width = 800, height = 600;
BufferedImage image = new BufferedImage(width, height, BufferedImage.TYPE_INT_ARGB);
Graphics2D g2d = image.createGraphics();
g2d.setColor(Color.WHITE);
g2d.fillRect(0, 0, width, height);
StreamingRenderer renderer = new StreamingRenderer();
renderer.setMapContent(map);
renderer.paint(g2d, new Rectangle(width, height), map.getMaxBounds());
g2d.dispose();
// 保存
javax.imageio.ImageIO.write(image, "png", new File("output/map.png"));
map.dispose();
Use SLD styles
import org.geotools.styling.*;
import org.geotools.factory.CommonFactoryFinder;
StyleFactory sf = CommonFactoryFinder.getStyleFactory();
FilterFactory2 ff = CommonFactoryFinder.getFilterFactory2();
// 创建面填充样式
Fill fill = sf.createFill(ff.literal(new Color(0, 128, 255, 128)));
Stroke stroke = sf.createStroke(ff.literal(Color.BLACK), ff.literal(1.0));
PolygonSymbolizer sym = sf.createPolygonSymbolizer(stroke, fill, null);
Rule rule = sf.createRule();
rule.symbolizers().add(sym);
FeatureTypeStyle fts = sf.createFeatureTypeStyle(new Rule[]{rule});
Style style = sf.createStyle();
style.featureTypeStyles().add(fts);
GeoJSON reading and writing
import org.geotools.geojson.feature.FeatureJSON;
import org.geotools.geojson.geom.GeometryJSON;
// 读取 GeoJSON 要素集
FeatureJSON fjson = new FeatureJSON();
SimpleFeatureCollection fc = fjson.readFeatureCollection(
new FileInputStream("data/points.geojson")
);
// 写入 GeoJSON
fjson.writeFeatureCollection(fc, new FileOutputStream("output/result.geojson"));
// 单个几何体 GeoJSON
GeometryJSON gjson = new GeometryJSON();
Geometry geom = gjson.read(new StringReader("{\"type\":\"Point\",\"coordinates\":[116.4,39.9]}"));
StringWriter sw = new StringWriter();
gjson.write(geom, sw);
WKT / WKB format conversion
import org.locationtech.jts.io.*;
// WKT
WKTReader wktReader = new WKTReader();
Geometry geom = wktReader.read("POLYGON((0 0,10 0,10 10,0 10,0 0))");
String wkt = new WKTWriter().write(geom);
// WKB
WKBReader wkbReader = new WKBReader();
Geometry geom2 = wkbReader.read(wkbBytes);
byte[] wkb = new WKBWriter().write(geom);
Typical application scenarios
| Scenario | Key classes / methods |
|---|---|
| Read Shapefile data | FileDataStoreFinder → SimpleFeatureSource.getFeatures() |
| Read and write GeoPackage | DataStoreFinder(dbtype=geopkg)→ SimpleFeatureStore |
| Connect to PostGIS database | DataStoreFinder(dbtype=postgis)→ SimpleFeatureStore |
| Read and write GeoJSON | FeatureJSON.readFeatureCollection() / writeFeatureCollection() |
| Coordinate system transformation (e.g. WGS84 → Web Mercator) | CRS.decode() → CRS.findMathTransform() → JTS.transform() |
| Attribute query | CQL.toFilter("NAME = 'xxx'") → featureSource.getFeatures(filter) |
| Spatial query (extent filtering) | CQL.toFilter("BBOX(the_geom, ...)") |
| Spatial relationship determination (contains, intersects, etc.) | Geometry.contains() / intersects() / within() |
| Buffer analysis | Geometry.buffer(distance) |
| Polygon overlay analysis (intersection / union / difference) | Geometry.intersection() / union() / difference() |
| Read GeoTIFF raster | GeoTiffReader.read() → GridCoverage2D |
| Map rendering output PNG | MapContent + StreamingRenderer.paint() |
| Create vector features and write | SimpleFeatureTypeBuilder → SimpleFeatureBuilder → SimpleFeatureStore |
| SLD style mapping | StyleFactory + PolygonSymbolizer / PointSymbolizer / LineSymbolizer |
Common notes
- Maven repository: GeoTools is not on Maven Central; the OSGeo repository must be configured (
https://repo.osgeo.org/repository/release/)。 - EPSG database: When using CRS functionality, it is necessary to include
gt-epsg-hsql(embedded) orgt-epsg-wkt(lightweight) module, otherwiseCRS.decode()will throw an exception. - Axis order: GeoTools follows the EPSG specification by default (latitude first); calling
CRS.decode("EPSG:4326", true)can force longitude first (lon/lat order). - Resource release:
DataStore、Reader、Writer、MapContentmust calldispose()after use to release resources.SimpleFeatureIteratormust be closed in try-with-resources or finally. - Thread safety:
DataStoreinstances are thread-safe and can be shared across multiple threads; however,SimpleFeatureIteratoris not thread-safe. - SPI mechanism: GeoTools uses Java SPI (ServiceLoader) to automatically discover DataStore factories, CRS factories, etc.; ensure the relevant module JARs are on the classpath.
- JTS version: GeoTools 28+ uses
org.locationtech.jts(instead of the oldcom.vividsolutions.jts); note the package name differences. - Performance optimization: For large data volume scenarios, use the
Queryobject to limit returned attributes and spatial extent, avoiding full loading; in PostGIS scenarios, it is recommended to enablepreparedStatements。 - Chinese Attributes: When Shapefile Chinese characters are garbled, create
ShapefileDataStoreand then callstore.setCharset(Charset.forName("GBK"))to set the encoding.
Reference Links
- GitHub repository: https://github.com/geotools/geotools
- Official documentation: https://docs.geotools.org/
- User guide: https://docs.geotools.org/stable/userguide/
- Javadoc: https://docs.geotools.org/stable/javadocs/
- Tutorial (Quickstart): https://docs.geotools.org/stable/userguide/tutorial/quickstart/index.html
- OSGeo Maven repository: https://repo.osgeo.org/repository/release/
- JTS Topology Suite: https://github.com/locationtech/jts