SuperAPI AI Directory

geotools

General & other

View repository

Updated 10-16 09:45

About this skill

Project URL: https://github.com/geotools/geotools

Maven GroupId: org.geotools

License: 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

  1. Maven repository: GeoTools is not on Maven Central; the OSGeo repository must be configured (https://repo.osgeo.org/repository/release/)。
  2. EPSG database: When using CRS functionality, it is necessary to include gt-epsg-hsql(embedded) or gt-epsg-wkt(lightweight) module, otherwise CRS.decode() will throw an exception.
  3. Axis order: GeoTools follows the EPSG specification by default (latitude first); calling CRS.decode("EPSG:4326", true) can force longitude first (lon/lat order).
  4. Resource release:DataStore、Reader、Writer、MapContent must call dispose() after use to release resources.SimpleFeatureIterator must be closed in try-with-resources or finally.
  5. Thread safety:DataStore instances are thread-safe and can be shared across multiple threads; however, SimpleFeatureIterator is not thread-safe.
  6. SPI mechanism: GeoTools uses Java SPI (ServiceLoader) to automatically discover DataStore factories, CRS factories, etc.; ensure the relevant module JARs are on the classpath.
  7. JTS version: GeoTools 28+ uses org.locationtech.jts(instead of the old com.vividsolutions.jts); note the package name differences.
  8. Performance optimization: For large data volume scenarios, use the Query object to limit returned attributes and spatial extent, avoiding full loading; in PostGIS scenarios, it is recommended to enable preparedStatements。
  9. Chinese Attributes: When Shapefile Chinese characters are garbled, create ShapefileDataStore and then call store.setCharset(Charset.forName("GBK")) to set the encoding.

Reference Links