Geotools

项目地址： https://github.com/geotools/geotools

Maven GroupId： org.geotools

许可证： LGPL 2.1

官方文档： https://docs.geotools.org/

概述

GeoTools 是一个成熟、模块化的开源 Java GIS 工具库，由 OSGeo 基金会管理，广泛应用于 GeoServer、uDig 等知名 GIS 平台。它提供：

• 矢量数据访问：Shapefile、GeoPackage、GeoJSON、PostGIS、Oracle Spatial、SQL Server 等
• 栅格数据访问：GeoTIFF、NetCDF、ImageMosaic 等
• 坐标参考系统 (CRS)：基于 EPSG 数据库的投影定义与坐标转换
• 空间查询与过滤：CQL / ECQL、OGC Filter 编码
• 地图渲染：基于 SLD/SE 的制图样式与图片输出
• OGC Web 服务：WMS / WFS / WCS 客户端
• 几何运算：基于 JTS Topology Suite 的全套几何计算

环境要求： JDK 11+（GeoTools 21–30）；JDK 17+（GeoTools 31+）

快速集成

Maven 仓库配置

GeoTools 发布在 OSGeo Maven 仓库，需在 pom.xml 中添加：

<repositories>
    <repository>
        <id>osgeo</id>
        <name>OSGeo Release Repository</name>
        <url>https://repo.osgeo.org/repository/release/</url>
    </repository>
</repositories>

常用模块依赖

<properties>
    <geotools.version><!-- 请查看 https://geotools.org/download.html 获取最新版 --></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>

核心模块一览

核心类一览

矢量数据读取与写入的完整示例见 reference/vector-io.md

坐标参考系统 (CRS) 与坐标转换

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[...]");

空间查询与过滤（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);

几何操作（基于 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);

栅格数据（GeoTIFF）与地图渲染的完整示例见 reference/raster-rendering.md GeoJSON 与 WKT/WKB 格式读写的完整示例见 reference/vector-io.md

典型应用场景

常见问题

1. Maven 仓库：GeoTools 不在 Maven Central 上，必须配置 OSGeo 仓库（https://repo.osgeo.org/repository/release/）。
2. EPSG 数据库：使用 CRS 功能时，需引入 gt-epsg-hsql（嵌入式）或 gt-epsg-wkt（轻量）模块，否则 CRS.decode() 会抛出异常。
3. 坐标轴顺序：GeoTools 默认遵循 EPSG 规范（纬度在前），调用 CRS.decode("EPSG:4326", true) 可强制经度在前（lon/lat 顺序）。
4. 资源释放：DataStore、Reader、Writer、MapContent 使用后必须调用 dispose() 释放资源。SimpleFeatureIterator 需在 try-with-resources 或 finally 中关闭。
5. 线程安全：DataStore 实例是线程安全的，可在多线程间共享；但 SimpleFeatureIterator 不是线程安全的。
6. SPI 机制：GeoTools 使用 Java SPI（ServiceLoader）自动发现 DataStore 工厂、CRS 工厂等，确保相关模块 JAR 在 classpath 中。
7. JTS 版本：GeoTools 28+ 使用 org.locationtech.jts（而非旧版 com.vividsolutions.jts），注意包名差异。
8. 性能优化：对大数据量场景，使用 Query 对象限制返回属性和空间范围，避免全量加载；PostGIS 场景建议开启 preparedStatements。
9. 中文属性：Shapefile 中文乱码时，创建 ShapefileDataStore 后调用 store.setCharset(Charset.forName("GBK")) 设置编码。

AI 使用建议

推荐工作流

1. 配置 Maven 仓库：在 pom.xml 中添加 OSGeo 仓库（https://repo.osgeo.org/repository/release/）
2. 引入必要模块：gt-main（核心）、gt-shapefile / gt-geopkg（数据源）、gt-epsg-hsql（CRS）、gt-cql（查询）、gt-render（渲染）
3. 打开数据源：使用 FileDataStoreFinder.getDataStore()（文件）或 DataStoreFinder.getDataStore(params)（数据库）
4. 执行查询：使用 CQL.toFilter() 构建过滤器 → featureSource.getFeatures(filter)
5. 处理结果：遍历 SimpleFeatureIterator，使用 JTS 几何方法进行空间运算
6. 释放资源：store.dispose()、关闭 SimpleFeatureIterator

关键注意事项

• Maven 仓库必需：GeoTools 不在 Maven Central，必须配置 OSGeo 仓库
• EPSG 数据库：使用 CRS 功能需引入 gt-epsg-hsql，否则 CRS.decode() 抛出异常
• 资源释放：DataStore、Reader、Writer、MapContent 使用后必须调用 dispose()
• 坐标轴顺序：GeoTools 默认遵循 EPSG 规范（纬度在前），使用 CRS.decode("EPSG:4326", true) 强制经度在前
• 线程安全：DataStore 线程安全可共享；SimpleFeatureIterator 非线程安全
• JTS 包名：GeoTools 28+ 使用 org.locationtech.jts（非旧版 com.vividsolutions.jts）

相关技能

• jts — JTS Topology Suite（GeoTools 几何计算核心）：../jts/SKILL.md
• geoserver — 基于 GeoTools 的地图服务器：../geoserver/SKILL.md
• postgis — 空间数据库：../postgis/SKILL.md
• opengis-utils-for-java — Java GIS 统一工具包：../opengis-utils-for-java/SKILL.md
• geometry-api-java — Esri Geometry API：../geometry-api-java/SKILL.md

参考资源

• GitHub 仓库： https://github.com/geotools/geotools
• 官方文档： https://docs.geotools.org/
• 用户指南： https://docs.geotools.org/stable/userguide/
• Javadoc： https://docs.geotools.org/stable/javadocs/
• 教程（Quickstart）： https://docs.geotools.org/stable/userguide/tutorial/quickstart/index.html
• OSGeo Maven 仓库： https://repo.osgeo.org/repository/release/
• JTS Topology Suite： https://github.com/locationtech/jts