Apache SIS 常用工具与 API 详解

目标：给出 Apache SIS 1.6 命令行八大子命令与核心 Java API 的速查手册。所有命令与回显均在 Ubuntu 22.04.5 + JDK 17 + SIS 1.6 实测（EPSG 完整库已安装），Java API 基于工程 sis-referencing:1.6 依赖编译运行通过。读罢即可在坐标参照系解析、WKT 格式化、测地线距离计算、坐标转换、元数据读取与格式转换等场景直接套用。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Java：OpenJDK 17.0.20.1
Apache SIS：1.6（命令行工具装于 /opt/sis/apache-sis-1.6；Java 依赖 org.apache.sis.core:sis-referencing:1.6 + org.apache.sis.non-free:sis-embedded-data:1.6 + org.apache.derby:derby:10.15.2.0）
大地数据集：EPSG 12.047 完整库（Derby 10.15）
演示账号：root

二、工具概览

sis 控制台共 8 个子命令（sis help 实测清单）：

子命令	功能	典型用法
help	帮助总览	`sis help`
about	版本与系统配置	`sis about`
mime-type	探测数据格式	`sis mime-type <file>`
metadata	ISO 19115 元数据	`sis metadata <file>`
crs	坐标参照系定义	`sis crs EPSG:4326`
identifier	识别已知对象标识	`sis identifier <file>`
transform	坐标转换/变换	`sis transform --sourceCRS ... --targetCRS ... <file>`
translate	格式转换重写	`sis translate --output <out> <file>`

Java API 侧核心入口四个：CRS.forCode / CRS.fromWKT（坐标系获取）、FormattableObject.toWKT（WKT 输出）、GeodeticCalculator（距离与方位角）、CRS.findOperation + MathTransform（坐标转换）。

三、前置条件

命令行工具随二进制发行包就绪（安装见《Apache SIS 安装指南》）。本文所有示例的输出约定：

export TERM=xterm-256color
export SIS_OPTS="--encoding UTF-8"

Java API 示例基于以下 Maven 依赖（工程构建详见《Apache SIS 构建并运行示例应用指南》）：

<dependency>
    <groupId>org.apache.sis.core</groupId>
    <artifactId>sis-referencing</artifactId>
    <version>1.6</version>
</dependency>
<dependency>
    <groupId>org.apache.sis.non-free</groupId>
    <artifactId>sis-embedded-data</artifactId>
    <version>1.6</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>org.apache.derby</groupId>
    <artifactId>derby</artifactId>
    <version>10.15.2.0</version>
    <scope>runtime</scope>
</dependency>

四、命令行工具详解

4.1 sis help

sis help

实测回显：

Apache SIS, Spatial Information System
Usage: sis <command> [options] [files]

Commands:
  help        Show a help overview.
  about       Show information about Apache SIS and system configuration.
  mime-type   Show MIME type for the given file.
  metadata    Show ISO 19115 metadata information for the given file.
  crs         Show Coordinate Reference System (CRS) information for the given file.
  identifier  Show identifiers for metadata and referencing systems in the given file.
  transform   Convert or transform coordinates from given source CRS to target CRS.
  translate   Rewrite a data file in another format.

Options:
  --sourceCRS  The Coordinate Reference System of input data.
  --targetCRS  The Coordinate Reference System of output data.
  --operation  The Coordinate Operation to apply on data (alternative to source and target CRS).
  --inverse    Use the inverse of the coordinate operation.
  --metadata   Relative path to an auxiliary metadata file.
  --output     The output file.
  --format     The output format. Examples: xml, wkt, wkt1 or text.
  --locale     The locale to use for the console output.
  --timezone   The timezone for the dates printed to the console output.
  --encoding   The encoding to use for some text inputs and for console output.
  --colors     Whether colorized output shall be enabled.
  --brief      Reduce the output to only brief information.
  --verbose    Request the output to contain more detailed information.
  --debug      Prints full stack trace in case of failure.
  --help       Lists the options available for a specific command.
（退出码 0）

注意：sis help crs 这种「help + 子命令参数」的形态不被支持，实测报 Expected at most 0 argument, but got 1.（退出码 3）；子命令帮助统一用 sis <command> --help。

4.2 sis about

查看版本与系统配置（等价于其它软件的 --version；SIS 无 --version 选项，实测报 Option ?version? is not recognized.）：

sis about

实测回显（EPSG 完整库安装后）：

Local configuration
  ├─Versions
  │   ├─Apache SIS………………………………… 1.6
  │   ├─Java………………………………………………… 17.0.20.1 (Ubuntu)
  │   ├─Operating system………………… Linux 6.8.0-138-generic (amd64)
  │   └─Geodetic dataset………………… EPSG geodetic dataset version 12.047 on "Apache Derby" version 10.15.
  ├─Localization
  │   ├─Locale…………………………………………… English (United States)
  │   │   └─ISO code…………………………… eng (US)
  │   ├─Timezone……………………………………… Greenwich Mean Time (GMT)
  │   │   └─Offset………………………………… UTC + 12:00 AM
  │   ├─Current date and time…… October 12, 2026 at 12:01:33 PM GMT
  │   └─Character encoding…………… US-ASCII (ANSI_X3.4-1968, cp367, csASCII, iso-ir-6, ASCII, iso_646.irv:1983, ANSI_X3.4-1986, ascii7, default, ISO_646.irv:1991, ISO646-US, IBM367, 646, us)
  ├─Plug-ins
  │   └─Data formats…………………………… 11 entries
  │       ├─Read……………………………………… NetCDF
  │       ├─Read/write/create…… World file
  │       ├─Read/write/create…… ASCII Grid
  │       ├─Read……………………………………… BIL/BIP/BSQ
  │       ├─Read……………………………………… CSV
  │       ├─Read……………………………………… XML
  │       ├─Read……………………………………… WKT
  │       ├─Read/write……………………… folder
  │       ├─Read/write/create…… GeoTIFF
  │       ├─Read……………………………………… Landsat
  │       └─Read/write/create…… GPS Exchange Format (GPX)
  ├─Logging
  │   ├─Implementation……………………… java.util.logging
  │   └─Level……………………………………………… CONFIG
  │       └─org.apache.sis…………… FINE
  └─Paths
      ├─User home directory………… /root
      ├─Current directory……………… /
      ├─Data directory……………………… /opt/sis/apache-sis-1.6/bin/../data
      ├─Java home directory………… /usr/lib/jvm/java-17-openjdk-amd64
      └─Temporary files…………………… /tmp
（退出码 0）

其中 Plug-ins 的 Data formats 清单即各子命令可读写的格式范围（NetCDF、GeoTIFF、CSV、WKT、XML、ASCII Grid、GPX 等）。

4.3 sis mime-type

sis mime-type RGB.byte.tif
sis mime-type demo.asc

实测回显：

RGB.byte.tif: image/tiff
（退出码 0）

demo.asc: text/plain
（退出码 0）

⚠️ 注意：对 SIS 不认识的文件，mime-type 静默无输出、退出码 0（实测表头 CSV 即此表现）；判断「格式是否受支持」应结合 metadata 命令的成功与否。

4.4 sis crs

两种用法：直接查 EPSG 代码定义；或从数据文件读取坐标参照系。

sis crs EPSG:4326

实测回显（完整 EPSG 库）：

GeographicCRS["WGS 84",
  Ensemble["World Geodetic System 1984 ensemble",
    Member["World Geodetic System 1984 (Transit)"],
    Member["World Geodetic System 1984 (G730)"],
    Member["World Geodetic System 1984 (G873)"],
    Member["World Geodetic System 1984 (G1150)"],
    Member["World Geodetic System 1984 (G1674)"],
    Member["World Geodetic System 1984 (G1762)"],
    Member["World Geodetic System 1984 (G2139)"],
    Member["World Geodetic System 1984 (G2296)"],
    Ellipsoid["WGS 84", 6378137.0, 298.257223563],
    EnsembleAccuracy[2.0]],
  CS[ellipsoidal, 2],
    Axis["Latitude (B)", north],
    Axis["Longitude (L)", east],
    Unit["degree", 0.017453292519943295],
  Usage[
    Scope["Horizontal component of 3D system."],
    Area["World"],
    BBox[-90.00, -180.00, 90.00, 180.00]],
  Id["EPSG", 4326, "12.047", URI["urn:ogc:def:crs:EPSG:12.047:4326"]]]
（退出码 0）

sis crs RGB.byte.tif

实测回显（从 GeoTIFF 读取投影信息并给出 EPSG 识别）：

ProjectedCRS["WGS 84 / UTM zone 18N",
  BaseGeogCRS["WGS 84",
    Ensemble["World Geodetic System 1984 ensemble",
      Member["World Geodetic System 1984 (Transit)"],
      Member["World Geodetic System 1984 (G730)"],
      Member["World Geodetic System 1984 (G873)"],
      Member["World Geodetic System 1984 (G1150)"],
      Member["World Geodetic System 1984 (G1674)"],
      Member["World Geodetic System 1984 (G1762)"],
      Member["World Geodetic System 1984 (G2139)"],
      Member["World Geodetic System 1984 (G2296)"],
      Ellipsoid["WGS 84", 6378137.0, 298.257223563],
      EnsembleAccuracy[2.0]],
    Unit["degree", 0.017453292519943295]],
  Conversion["UTM zone 18N",
    Method["Transverse Mercator"],
    Parameter["Latitude of natural origin", 0.0],
    Parameter["Longitude of natural origin", -75.0],
    Parameter["Scale factor at natural origin", 0.9996],
    Parameter["False easting", 500000.0],
    Parameter["False northing", 0.0]],
  CS[Cartesian, 2],
    Axis["Easting (E)", east],
    Axis["Northing (N)", north],
    Unit["metre", 1],
  Usage[
    Scope["Navigation and medium accuracy spatial referencing."],
    Area["Between 78°W and 72°W, northern hemisphere between equator and 84°N, onshore and offshore. Bahamas. Canada - Nunavut; Ontario; Quebec. Colombia. Cuba. Ecuador. Greenland. Haiti. Jamaica. Panama. Turks and Caicos Islands. United States (USA). Venezuela."],
    BBox[0.00, -78.00, 84.00, -72.00]],
  Id["EPSG", 32618, "12.047", URI["urn:ogc:def:crs:EPSG:12.047:32618"]]]
（退出码 0）

4.5 sis identifier

对含模糊定义的 WKT 文件做权威标识匹配（官方示例文件 MissingIdentifier.wkt，其 WKT 无 Id 但与 EPSG:27572 定义一致）：

sis identifier /root/sis-examples/MissingIdentifier.wkt

实测回显：

    urn:ogc:def:crs:EPSG:12.047:27572    | NTF (Paris) / Lambert zone II
（退出码 0）

4.6 sis transform

把 CSV 坐标从 NAD27（EPSG:4267）转到 WGS84（EPSG:4326），使用官方示例 AmericanCities.csv（仅含纬度、经度两列数字，逗号分隔）：

sis transform --sourceCRS EPSG:4267 --targetCRS EPSG:4326 /root/sis-examples/AmericanCities.csv

实测回显：

INFO    [NADCON] Datum shift files are searched in the
?       ?/opt/sis/apache-sis-1.6/data/DatumChanges? directory.
WARNING [CoordinateOperationFinder] Cannot find NADCON file named
?       ?conus.las?.
# Source:      NAD27 (EPSG:4267)
# Destination: WGS 84 (EPSG:4326)
# Operations:  NAD27 to WGS 84 (4) (EPSG:1173)
# Domain:      United States (USA) - CONUS onshore
# Accuracy:    10.0 metres

   Latitude (°),  Longitude (°)
   37.782901014, -122.418050348
   40.713000277,  -74.005569276
   34.050019413, -118.250896545
   29.763241677,  -95.383237554
   41.837014424,  -87.685018427
   25.775376502,  -80.208807338
（退出码 0）

头注信息完整给出了操作码（EPSG:1173）、适用域与精度（10 米）；未安装 NADCON 格网文件时 SIS 自动回退到 EPSG 数据集内置的基准变换，不影响结果输出。配套选项 --inverse（逆变换）、--operation（直接指定操作）见 sis transform --help。

4.7 sis metadata

读取 ISO 19115 元数据。GeoTIFF 实测（sis metadata --help 先查支持选项；--brief 对 metadata 不支持，实测报 Option ?brief? is not recognized.）：

sis metadata /root/sis-examples/RGB.byte.tif

实测回显（节选，完整树形输出较长）：

Metadata
  ├─Metadata identifier……………………………………………………………… RGB.byte
  ├─Spatial representation info
  │   ├─Axis dimension properties (1 of 2)…………… Column
  │   │   ├─Resolution………………………………………………………………… 300.037926675095
  │   │   └─Dimension size……………………………………………………… 791
  │   ├─Axis dimension properties (2 of 2)…………… Row
  │   │   ├─Resolution………………………………………………………………… 300.041782729805
  │   │   └─Dimension size……………………………………………………… 718
  │   ├─Cell geometry…………………………………………………………………… Area
  │   ├─Transformation parameter availability…… True
  │   ├─Check point availability……………………………………… False
  │   ├─Point in pixel………………………………………………………………… Upper left
  │   ├─Transformation dimension description……… WGS 84 / UTM zone 18N
  │   └─Number of dimensions………………………………………………… 2
  ├─Reference system info………………………………………………………… EPSG:WGS 84 / UTM zone 18N
  ├─Identification info
  │   ├─Citation………………………………………………………………………………… RGB.byte
  │   │   └─Identifier………………………………………………………………… RGB.byte
  │   ├─Spatial representation type……………………………… Grid
  │   ├─Spatial resolution (1 of 2)
  │   │   └─Distance……………………………………………………………………… 300.037926675095
  │   ├─Spatial resolution (2 of 2)
  │   │   └─Distance……………………………………………………………………… 300.041782729805
  │   ├─Extent
  │   │   └─Geographic element
  │   │       ├─West bound longitude…………………………… 78°57′31.1398754183″W
  │   │       ├─East bound longitude…………………………… 76°34′29.725320496″W
  │   │       ├─South bound latitude…………………………… 23°33′53.9683592114″N
  │   │       ├─North bound latitude…………………………… 25°33′03.1455627618″N
  │   │       └─Extent type code……………………………………… True
  │   └─Resource format
  │       ├─Format specification citation……………… GeoTIFF Coverage Encoding Profile
  │       │   ├─Alternate title………………………………………… GeoTIFF
  │       │   └─Other citation details……………………… Read with Apache Spatial Information System version 1.6.
  │       └─File decompression technique………………… None
  ├─Content info
  │   └─Attribute group
  │       ├─Attribute (1 of 3)…………………………………………… Red
  │       │   ├─Max value………………………………………………………… 255
  │       │   ├─Min value………………………………………………………… 0
  │       │   ├─Scale factor………………………………………………… 1
  │       │   ├─Offset………………………………………………………………… 0
  │       │   └─Bits per value…………………………………………… 8
  │       ├─Attribute (2 of 3)…………………………………………… Green
  │       ├─Attribute (3 of 3)…………………………………………… Blue
  ├─Metadata scope
  │   └─Resource scope………………………………………………………………… COVERAGE
  └─Locale………………………………………………………………………………………………… English
      └─Character set…………………………………………………………………… US-ASCII
（退出码 0）

对 ASCII Grid 同样可用（实测 demo.asc 可读，缺失 demo.prj 辅助文件时输出 WARNING 与 NoSuchFileException 堆栈但不影响结果）；对无表头的普通 CSV 则报 Format of ?AmericanCities.csv? is not recognized.（实测退出码 199）。

4.8 sis translate

数据格式转换重写。ASCII Grid 转 GeoTIFF 实测：

sis translate --output /root/sis-examples/demo.tiff /root/sis-examples/demo.asc
ls -lh demo.tiff
sis mime-type demo.tiff

实测回显（转换过程对缺失 .prj 输出 WARNING 堆栈后成功）：

WARNING [AsciiGridStore] Cannot read the ?prj? auxiliary file.
（NoSuchFileException demo.prj 堆栈，中略）
（退出码 0）
-rw-r--r-- 1 root root 476 Oct 12 12:07 demo.tiff
demo.tiff: image/tiff

产物可直接被 sis metadata/sis crs 再读取，形成格式互转闭环。

五、Java API 详解

5.1 CRS.forCode 与 CRS.fromWKT

获取坐标参照系的两个入口（org.apache.sis.referencing.CRS 静态方法）：

// 按 EPSG 代码解析（需完整 EPSG 数据集支撑，见前置条件）
CoordinateReferenceSystem wgs84 = CRS.forCode("EPSG:4326");

// 按 WKT 2 文本解析（无需数据集）
String wkt = "PROJCRS[\"WGS 84 / UTM zone 50N\", BASEGEODCRS[\"WGS 84\", "
        + "DATUM[\"World Geodetic System 1984\", ELLIPSOID[\"WGS 84\", 6378137, 298.257223563]]], "
        + "CONVERSION[\"UTM zone 50N\", METHOD[\"Transverse Mercator\"], "
        + "PARAMETER[\"Longitude of natural origin\", 117], PARAMETER[\"False easting\", 500000]], "
        + "CS[Cartesian,2], AXIS[\"(E)\",east], AXIS[\"(N)\",north], LENGTHUNIT[\"metre\",1]]";
CoordinateReferenceSystem utm50 = CRS.fromWKT(wkt);
System.out.println("parsed = " + utm50.getName().getCode() + " | " + utm50.getClass().getSimpleName());

实测回显：

parsed = WGS 84 / UTM zone 50N | DefaultProjectedCRS

5.2 FormattableObject.toWKT

SIS 实现类继承 org.apache.sis.io.wkt.FormattableObject，toWKT() 输出标准 WKT 2 文本：

System.out.println(((FormattableObject) wgs84).toWKT());

实测回显：

GEOGCRS["WGS 84",
  ENSEMBLE["World Geodetic System 1984 ensemble",
    MEMBER["World Geodetic System 1984 (Transit)"],
    MEMBER["World Geodetic System 1984 (G730)"],
    MEMBER["World Geodetic System 1984 (G873)"],
    MEMBER["World Geodetic System 1984 (G1150)"],
    MEMBER["World Geodetic System 1984 (G1674)"],
    MEMBER["World Geodetic System 1984 (G1762)"],
    MEMBER["World Geodetic System 1984 (G2139)"],
    MEMBER["World Geodetic System 1984 (G2296)"],
    ELLIPSOID["WGS 84", 6378137.0, 298.257223563, LENGTHUNIT["metre", 1]],
    ENSEMBLEACCURACY[2.0]],
    PRIMEM["Greenwich", 0.0, ANGLEUNIT["degree", 0.017453292519943295]],
  CS[ellipsoidal, 2],
    AXIS["Latitude (B)", north, ORDER[1], AXISMINVALUE[-90.0], AXISMAXVALUE[90.0], RANGEMEANING[exact]],
    AXIS["Longitude (L)", east, ORDER[2], AXISMINVALUE[-180.0], AXISMAXVALUE[180.0], RANGEMEANING[wraparound]],
    ANGLEUNIT["degree", 0.017453292519943295],
  USAGE[
    SCOPE["Horizontal component of 3D system."],
    AREA["World"],
    BBOX[-90.00, -180.00, 90.00, 180.00]],
  ID["EPSG", 4326, "12.047", URI["urn:ogc:def:crs:EPSG:12.047:4326"]]]

💡 注意：SIS 1.6 已无旧资料中的 org.apache.sis.io.wkt.Formattable 接口，直接引用会编译报 cannot find symbol，改用 FormattableObject。

5.3 GeodeticCalculator 测地线距离

创建入口为静态工厂 GeodeticCalculator.create(crs)（构造器不对外公开）。setStartGeographicPoint/setEndGeographicPoint 的参数序为（纬度，经度）：

GeodeticCalculator calc = GeodeticCalculator.create(wgs84);
calc.setStartGeographicPoint(48.8566, 2.3522);   // 巴黎
calc.setEndGeographicPoint(35.6762, 139.6503);   // 东京
System.out.println("geodesic distance = " + calc.getGeodesicDistance() + " metres");

实测回显：

geodesic distance = 9735308.654239194 metres

约 9735.3 公里，为沿 WGS84 椭球的测地线（大圆）距离；同类方法还有 getStartingAzimuth()（起始方位角）、getRhumblineLength()（恒向线距离）。

5.4 CRS.findOperation 与 MathTransform

坐标转换三步：解析源/目标 CRS → 查找坐标操作 → 执行变换。务必传入感兴趣区域以获得权威 EPSG 操作：

CoordinateReferenceSystem source = CRS.forCode("EPSG:4267");
CoordinateReferenceSystem target = CRS.forCode("EPSG:4326");
CoordinateOperation op = CRS.findOperation(source, target,
        new DefaultGeographicBoundingBox(-125.0, -66.0, 24.0, 50.0));   // 美国 CONUS 范围
MathTransform mt = op.getMathTransform();

// EPSG:4267 轴序为 (纬度, 经度)
DirectPosition p1 = new DirectPosition2D(source, 37.783, -122.417);
DirectPosition p2 = mt.transform(p1, null);
System.out.println("operation = " + op.getName().getCode());
System.out.println("output = " + p2.getOrdinate(0) + ", " + p2.getOrdinate(1));

实测回显：

operation = NAD27 to WGS 84 (4)
output = 37.78290101412837, -122.41805034782497

与命令行 sis transform 同场景结果一致（操作码 EPSG:1173，精度 10 米）。实测对照：当区域参数传 null 时，SIS 可能返回名为 SIS:Unspecified datum change 的兜底操作（无基准改正参数，输出 37.78092407226795, -122.41700000000002），生产环境不可接受。

六、注意事项

⚠️ 注意：

sis 子命令帮助统一为 sis <command> --help；sis help <command> 会报「Expected at most 0 argument」。

无 sis --version 选项，版本信息看 sis about。

mime-type 对不认识的对象静默返回（退出码 0），格式支持性以 metadata 能否成功为准。

Java 侧 GeodeticCalculator 用 create() 静态工厂；FormattableObject 替代已移除的 Formattable。

坐标转换必须提供 DefaultGeographicBoundingBox 感兴趣区域，否则可能落到无参数的兜底 datum change。

setStartGeographicPoint 等方法参数序为（纬度，经度）；DirectPosition2D(crs, x, y) 中 x/y 依该 CRS 声明的轴序，EPSG 地理坐标系多为（纬度，经度）。

七、常见问题

Q1：sis crs EPSG:6676 报 only a subset ... ？ 内置仅为 EPSG 子集。交互终端重跑同一命令按提示安装完整库；或应用侧引入 sis-embedded-data（见《Apache SIS 配置参数详解》3.3 节）。

Q2：日志行出现 ? 字符？ 日志通道默认 US-ASCII 编码所致（--encoding UTF-8 只管命令输出），数据本身无损；详见安装指南 FAQ Q5。

Q3：CRS.fromWKT 解析成功但打印一行 WARNING: The ?SIS_DATA? environment variable is not set.？ 该告警来自元数据 SQL 通道探测（无任何 EPSG 数据集时的初始化检查），WKT 解析与输出不受影响；引入 sis-embedded-data 或配置 SIS_DATA 后消失。

Q4：findOperation 结果叫 SIS:Unspecified datum change？ EPSG 工厂未接入或区域未指定。确认 sis-embedded-data + derby:10.15.2.0 依赖齐全，并传入感兴趣区域（见 5.4 节实测对照）。

Q5：GeoTIFF 的 CRS 是 EPSG:32618，为什么应用里想输出 EPSG:4326 的 WKT？ 先用 sis crs <file> 或 CRS.forCode 拿到源 CRS，再按 5.4 节做 findOperation 到目标 CRS 后变换坐标；toWKT() 输出的是坐标参照系定义本身，与坐标点变换是两回事。

八、参考链接

命令行工具文档：https://sis.apache.org/command-line.html
官方示例文件：https://sis.apache.org/examples/
下载与 Maven 依赖：https://sis.apache.org/downloads.html
EPSG 数据集接入：https://sis.apache.org/epsg.html
Javadoc（1.6）：https://sis.apache.org/apidocs/