Apache Commons Imaging 常用 CLI 命令与工具详解

目标：整理围绕 Apache Commons Imaging 1.0.0-alpha6 的日常命令行工具链——Maven 构建命令、java/javac 运行命令、Python3+Pillow 图像辅助命令、官方 bin 包配套工具（jar/javap/sha512sum），每条命令附实测回显，已在 Ubuntu 22.04.5 LTS 实测通过。

一、环境信息

本节列出本文实测环境与工具版本。

工具	版本（实测）	用途
Java	OpenJDK 17.0.20.1	运行/编译
Maven	3.6.3	依赖与构建
Python3 + Pillow	3.10 / 9.0.1	生成测试图片
commons-imaging	1.0.0-alpha6	图像处理库
项目目录	/opt/imaging-lab/maven	Maven 工程

二、工具概览

Apache Commons Imaging 是 Java 库，本身不提供独立 CLI 可执行程序；其「命令行」由配套工具链构成，各司其职：

工具	典型命令	职责
Maven	mvn compile / dependency:tree	拉依赖、编译、查看依赖树
javac	javac -cp <classpath> 源文件	离线/脚本方式编译
java	java -Xmx256m -cp <classpath> 主类	运行读图/转格式程序
Python3+Pillow	python3 生成图脚本	造测试图片、辅助比对
jar/javap	jar tf / javap -cp <jar> 类名	查看 jar 内容与 API 签名
sha512sum	sha512sum -c	校验官方包完整性

💡 说明：命令行没有「graphics 命令」直读图片元数据（库能力需通过 Java 代码调用，见《快速入门与集成示例》篇）；本文把从装依赖到验证结果的完整命令链逐一给出可独立执行的形态。

三、前置条件

已按《Ubuntu 22.04 安装 Apache Commons Imaging 指南》完成 JDK 17 + Maven 安装；
项目 /opt/imaging-lab/maven 已创建，pom 已声明 commons-imaging 1.0.0-alpha6；
测试图片 /opt/imaging-lab/test.png 已生成。

四、Maven 命令详解

Maven 是依赖与构建的入口，本节命令均在 /opt/imaging-lab/maven 下执行。

4.1 mvn -version：查看版本与环境

mvn -version

输出（实测）：

Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64

要点：Java version 一行确认 Maven 运行在 JDK 17，否则先设 export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64。

4.2 mvn clean compile：清理并编译

cd /opt/imaging-lab/maven && mvn clean compile

输出节选（实测）：

[INFO] Deleting /opt/imaging-lab/maven/target
[INFO] --- maven-compiler-plugin:3.11.0:compile (default-compile) @ imaging-lab ---
[INFO] Compiling 1 source file with javac [debug target 17] to target/classes
[INFO] BUILD SUCCESS
[INFO] Total time:  3.866 s

要点：BUILD SUCCESS 表示依赖解析与编译全部通过；首次执行会下载 commons-imaging 及其传递依赖到 /root/.m2/repository。

4.3 mvn dependency:tree：查看依赖树

mvn dependency:tree

输出节选（实测）：

[INFO] \- org.apache.commons:commons-imaging:jar:1.0.0-alpha6:compile
[INFO]    +- commons-io:commons-io:jar:2.19.0:compile
[INFO]    \- org.apache.commons:commons-lang3:jar:3.17.0:compile
[INFO] BUILD SUCCESS

要点：可见传递依赖 commons-io 2.19.0 与 commons-lang3 3.17.0，离线分发或 bin 包直用时需手动准备这两个 jar。

4.4 mvn dependency:build-classpath：生成运行 classpath

mvn dependency:build-classpath -Dmdep.outputFile=cp.txt
cat cp.txt

输出（实测）：

/root/.m2/repository/org/apache/commons/commons-imaging/1.0.0-alpha6/commons-imaging-1.0.0-alpha6.jar:/root/.m2/repository/commons-io/commons-io/2.19.0/commons-io-2.19.0.jar:/root/.m2/repository/org/apache/commons/commons-lang3/3.17.0/commons-lang3-3.17.0.jar

要点：该命令把编译产物之外的运行 classpath 写入 cp.txt，与 java -cp "target/classes:$(cat cp.txt)" 组合即可运行。

4.5 mvn dependency:list：核对生效版本

mvn dependency:list | grep commons-imaging

输出节选（实测）：

[INFO]    org.apache.commons:commons-imaging:jar:1.0.0-alpha6:compile
[INFO] BUILD SUCCESS

五、java / javac 命令详解

5.1 java -version：验证 JDK

java -version

输出（实测）：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

5.2 java 运行带 -Xmx 与 -cp

cd /opt/imaging-lab/maven
java -Xmx256m -cp "target/classes:$(cat cp.txt)" HelloImaging /opt/imaging-lab/test.png

输出（实测）：

Hello Apache Commons Imaging 1.0.0-alpha6
  file        : /opt/imaging-lab/test.png
  guessFormat : PNG
  formatName  : PNG Portable Network Graphics
  size        : 800 x 600 px
  bitsPerPixel: 24
  physicalDpi : 300 x 300 dpi

参数速查：

参数	本例值	说明
-Xms/-Xmx	256m / 256m-512m	初始堆/堆上限，图片批处理建议区间
-cp	target/classes:$(cat cp.txt)	编译产物 + 依赖 classpath
-XX:+PrintCommandLineFlags	可选	打印生效 JVM 标志（验证 -Xmx）

5.3 javac 离线编译

bin 包直用场景（classpath 指向官方 jar 与依赖）：

cd /opt/imaging-lab/bin
CP="commons-imaging-1.0.0-alpha6/commons-imaging-1.0.0-alpha6.jar:commons-imaging-1.0.0-alpha6/commons-io-2.19.0.jar:commons-imaging-1.0.0-alpha6/commons-lang3-3.17.0.jar"
javac -cp "$CP" HelloImaging.java
java -Xmx256m -cp ".:$CP" HelloImaging /opt/imaging-lab/test.png

输出（实测）：

Hello Apache Commons Imaging 1.0.0-alpha6
  file        : /opt/imaging-lab/test.png
  guessFormat : PNG
  formatName  : PNG Portable Network Graphics
  size        : 800 x 600 px
  bitsPerPixel: 24
  physicalDpi : 300 x 300 dpi

六、Python3 + Pillow 图像辅助命令

6.1 生成测试图片

python3 - <<'EOF'
from PIL import Image, ImageDraw
img = Image.new("RGB", (800, 600))
for y in range(600):
    for x in range(800):
        img.putpixel((x, y), (int(x/800*255), int(y/600*255), 128))
d = ImageDraw.Draw(img)
d.rectangle([50, 50, 250, 150], outline=(255, 255, 255), width=3)
img.save("/opt/imaging-lab/test.png", dpi=(300, 300))
print("generated")
EOF

输出（实测）：

generated

6.2 读图片基本信息（与库结果交叉比对）

python3 - <<'EOF'
from PIL import Image
im = Image.open("/opt/imaging-lab/test.png")
print(im.format, im.size, im.info.get("dpi"))
EOF

输出（实测）：

PNG (800, 600) (299.9994, 299.9994)

要点：Pillow 与 Commons Imaging 对同一张图给出一致结论（PNG、800x600、约 300DPI），可互为验证手段。

七、官方 bin 包配套工具

7.1 jar tf：查看 jar 内容

cd /opt/imaging-lab/bin/commons-imaging-1.0.0-alpha6
jar tf commons-imaging-1.0.0-alpha6.jar | head -8

输出（实测）：

META-INF/
META-INF/MANIFEST.MF
org/
org/apache/
org/apache/commons/
org/apache/commons/imaging/
org/apache/commons/imaging/bytesource/
org/apache/commons/imaging/color/

7.2 javap：查看 API 签名（排查方法名/参数）

javap -cp commons-imaging-1.0.0-alpha6.jar org.apache.commons.imaging.Imaging | grep writeImage

输出（实测）：

public static void writeImage(java.awt.image.BufferedImage, java.io.File, org.apache.commons.imaging.ImageFormat) throws org.apache.commons.imaging.ImagingException, java.io.IOException;
public static void writeImage(java.awt.image.BufferedImage, java.io.OutputStream, org.apache.commons.imaging.ImageFormat) throws org.apache.commons.imaging.ImagingException, java.io.IOException;
public static byte[] writeImageToBytes(java.awt.image.BufferedImage, org.apache.commons.imaging.ImageFormat) throws org.apache.commons.imaging.ImagingException, java.io.IOException;

要点：从该回显可确认 1.0.0-alpha6 的 writeImage 只有三参版本（无参数重载），与《配置参数详解》篇 5.4 的结论一致。

7.3 sha512sum：校验发布包

cd /opt/imaging-lab/bin
(echo "$(awk '{print $1}' commons-imaging-1.0.0-alpha6-bin.tar.gz.sha512)  commons-imaging-1.0.0-alpha6-bin.tar.gz" | sha512sum -c -)

输出（实测）：

commons-imaging-1.0.0-alpha6-bin.tar.gz: OK

官方 sha512（实测）：

820e694cba60e4b1fc8770bed935fd56125565a3a9e1bd5ac38c2ec461eaf621fb14faedb446d3b59e2c85143b8e6903eabc4e5f1f62cae292640bd4f627f234

八、注意事项

所有 mvn 命令须在项目根（含 pom.xml）执行，否则报 [ERROR] Malformed POM 或找不到工程；
$(cat cp.txt) 依赖 4.4 生成的 cp.txt，删除 target 后需重新生成；
classpath 中 jar 缺一不可：漏 commons-io 会抛 NoClassDefFoundError: org/apache/commons/io/build/AbstractOrigin（实测踩坑）；
java 运行大图批处理时，-Xmx 不要超过 512m（库单图内存占用低，大堆无收益且浪费）；
javap 查看带 $ 的内部类需加引号（如 javap "org.apache.commons.imaging.formats.tiff.TiffImageMetadata\$Directory"）。

九、常见问题（FAQ）

Q1：mvn dependency:build-classpath 报 UnknownLifecyclePhase？

该目标属于 maven-dependency-plugin，3.x 默认绑定；若自定义 pom 禁用了默认插件，改为 mvn org.apache.maven.plugins:maven-dependency-plugin:3.6.1:build-classpath -Dmdep.outputFile=cp.txt。

Q2：java 运行报 ClassNotFoundException: ImagingLab？

主类没编译进 target/classes（编译失败或类名不匹配）。先 mvn -q compile 确认 BUILD SUCCESS，并核对主类名与 -cp 首项 target/classes。

Q3：javap 查不到方法？

版本 API 可能变更（alpha 阶段）。用 jar tf commons-imaging-1.0.0-alpha6.jar | grep 类名 确认类存在与包路径，再 javap 全限定名。

Q4：sha512sum 校验显示 FAILED？

重新下载（网络中断导致文件损坏），勿使用校验失败的文件；必要时比对官方 sha512 原文（见 7.3）。

十、参考链接

Maven 官方文档：https://maven.apache.org/guides/getting-started/
maven-dependency-plugin：https://maven.apache.org/plugins/maven-dependency-plugin/
Pillow 官方文档：https://pillow.readthedocs.io/
commons-imaging 下载目录：https://downloads.apache.org/commons/imaging/binaries/
Javadoc 在线 API：https://commons.apache.org/proper/commons-imaging/apidocs/