X5 Crop v4.0.1

X5 Crop v4.0.1

中文说明

V4.0.1 是 V4.0 之后的窄范围兼容更新，重点解决普通 135 长图里“肉眼分隔很清楚，但黑色片距比旧规则更宽”的情况。

快速使用

1. 下载本 Release 的 X5-Crop-v4.0.1.zip，不要下载 GitHub 自动生成的 Source code 压缩包。
2. 第一次使用先运行安装启动器：macOS 双击 install/X5_Crop_Mac_install.command；Windows 双击 install/X5_Crop_win_install.bat。
3. 安装完成后，把 X5_Crop.py 和对应系统主启动器放进 TIFF 长图文件夹：macOS 使用 X5_Crop_Mac.command，Windows 使用 X5_Crop_win.bat。
4. 双击主启动器，按提示选择 format、partial mode 和 Debug Analysis。

本版更新

• 新增正式 wide-separator 分支，用于普通 135 full strip 的宽黑色分隔条。
• 默认窄分隔检测仍保持 V4.0 行为；只有普通 separator 候选没有通过 auto gate 时，才尝试宽分隔条。
• wide-separator 要求黑带均值和相对突出度达标，并单独记录为 wide_detected_gaps / wide_gap_retry。
• 包含宽分隔条的候选有轻微 confidence cap，避免宽黑带把困难图误推成过高置信。
• wide-separator 只对普通 135 full strip 启用；half、xpan、120 和 135-dual 暂不启用。
• 新增仓库内诊断启动器 X5_Crop_Mac_diagnostics.command，用于本地开发测试；它不会放进用户 Release 包。

验证结果

• python3 X5_Crop.py --version 输出 X5_Crop.py 4.0.1。
• python3 -m py_compile X5_Crop.py x5crop/*.py x5crop/detection/*.py x5crop/debug/*.py 通过。
• 新增 4 张宽片距 135 样本从 V4.0 的 needs_review 变为 4 个 approved_auto，报告里均出现宽分隔相关记录。
• 既有全量 Test/135 dry run 保持 42 个 approved_auto / 6 个 needs_review。
• 使用 python3 -m x5crop.regression 对比既有 135 报告和 V4.0.1 临时报告，48 行在 status、confidence、review_reasons、outer_box、frame_boxes、gaps 上均为 0 diff。
• Release zip 只包含用户需要的脚本、启动器、TXT 文档和 install 目录；不包含 x5crop/、archive、CHANGELOG、AGENTS、LICENSE、诊断启动器或测试输出。

包校验

X5-Crop-v4.0.1.zip SHA-256：

5496ecf79fd725f20f487569e0ffb560496f52350e9e9fdfcd1fdeb836c9c5cf

---

English Notes

V4.0.1 is a narrow compatibility update after V4.0. It focuses on normal 135 strips where the gutter is visually clear but wider than the previous separator-width rule allowed.

Quick Start

1. Download X5-Crop-v4.0.1.zip from this Release. Do not use GitHub’s auto-generated Source code zip.
2. On first use, run the installer launcher: on macOS, double-click install/X5_Crop_Mac_install.command; on Windows, double-click install/X5_Crop_win_install.bat.
3. After installation, place X5_Crop.py and the platform launcher in the TIFF strip folder: X5_Crop_Mac.command for macOS, X5_Crop_win.bat for Windows.
4. Double-click the main launcher and choose format, partial mode, and Debug Analysis when prompted.

Changes

• Adds the formal wide-separator branch for wide dark gutters in normal 135 full strips.
• Keeps the default narrow-separator behavior from V4.0; wide separator retry only runs when the normal separator candidate fails the auto gate.
• Requires accepted wide separators to satisfy mean-score and relative-prominence gates, and records them as wide_detected_gaps / wide_gap_retry.
• Applies a light confidence cap to candidates containing wide separators, so wide gutters do not inflate confidence too aggressively.
• Enables wide-separator only for normal 135 full strips; half-frame, xpan, 120 formats, and 135-dual remain disabled for now.
• Adds the repository diagnostic launcher X5_Crop_Mac_diagnostics.command for local development testing; it is not included in user Release packages.

Verification

• python3 X5_Crop.py --version prints X5_Crop.py 4.0.1.
• python3 -m py_compile X5_Crop.py x5crop/*.py x5crop/detection/*.py x5crop/debug/*.py passed.
• Four new wide-gutter 135 samples changed from V4.0 needs_review to 4 approved_auto, with wide-separator records in the reports.
• The existing full Test/135 dry run remained 42 approved_auto / 6 needs_review.
• python3 -m x5crop.regression compared the existing 135 report against the V4.0.1 temporary report, with 0 diffs across all 48 rows for status, confidence, review_reasons, outer_box, frame_boxes, and gaps.
• The Release zip contains only the user-facing script, launchers, TXT docs, and install folder; it excludes x5crop/, archive snapshots, CHANGELOG, AGENTS, LICENSE, diagnostic launcher, and test outputs.

Package Checksum

X5-Crop-v4.0.1.zip SHA-256:

5496ecf79fd725f20f487569e0ffb560496f52350e9e9fdfcd1fdeb836c9c5cf

X5 Crop v4.0

中文说明

V4.0 是当前稳定发布版。它把源码重写成模块化 V4 架构，但 Release 包继续提供单文件 X5_Crop.py，普通用户仍然只需要脚本本体和对应系统启动器。

请下载本页面 Assets 里的 X5-Crop-v4.0.zip。不要下载 GitHub 自动生成的 Source code / 源码压缩包；源码包是开发结构，不是整理好的用户发布包。

脚本不会修改原始 TIFF。自动裁切会生成新文件；进入 needs_review/ 的文件是原 TIFF 副本，方便人工处理。

快速使用

1. 解压 X5-Crop-v4.0.zip。
2. 第一次使用先运行安装启动器：
   • macOS: 双击 install/X5_Crop_Mac_install.command
   • Windows: 双击 install\X5_Crop_win_install.bat
3. 安装完成后，把 X5_Crop.py、对应系统主启动器和 TIFF 长图放在同一个文件夹：
   • macOS 主启动器：X5_Crop_Mac.command
   • Windows 主启动器：X5_Crop_win.bat
4. 双击主启动器，按提示选择 format、partial mode 和 Debug Analysis。

Release 包内容

X5_Crop.py
X5_Crop_Mac.command
X5_Crop_win.bat
README.txt
快速启动_Quick_Start.txt
install/
  X5_Crop_Mac_install.command
  X5_Crop_win_install.bat
  X5_Crop_Mac_uninstall.command
  X5_Crop_win_uninstall.bat

Release 里的 X5_Crop.py 是单文件发布版，已经内置内部 x5crop/ 代码。普通用户不需要复制 x5crop/ 文件夹。

V4.0 主要变化

• 模块化 V4 架构：检测、几何、证据缓存、TIFF I/O、Debug Analysis、report 复用、deskew、CLI 和 regression 已拆分到 x5crop/ 内部模块。
• Release 包继续保持简单：只包含单文件脚本、两个主启动器、两个安装器、两个卸载器、README 和快速启动文档。
• 全量 135 default-deskew dry run 对比 V3.9：status、confidence、review_reasons、outer_box、frame_boxes 和 gaps 为 0 diff。
• 相比 V3.6.2 稳定版，V4 保留后续开发中已验证的保守修正，例如 lucky-pass 风险样本进入 REVIEW、部分红框/外框路径更稳。
• 默认输出 bleed：长轴 20px，短轴 10px；如果检测到叠片、近似叠片或连续内容风险，长轴输出 bleed 会自动提高到 50px。bleed 只影响最终输出，不参与检测评分。
• 文档明确说明：自动裁切输出 TIFF 会保留原 TIFF 的画质相关属性，包括位深、通道结构、ICC / 色彩空间、resolution 和 metadata；裁切不会主动降位深、改色、压缩或重采样。
• Release 包内用户文档改为 README.txt 和 快速启动_Quick_Start.txt，方便不同系统直接打开阅读；仓库源文档仍保留 Markdown 格式。
• 文档结构更清晰：README 作为完整用户手册，不再重复快速启动步骤和版本更新日志；快速操作见 快速启动_Quick_Start.md，版本差异见 CHANGELOG.md。
• 当前版本主要针对普通 135 全量回归测试和优化；其它 format 可用，但建议先用 Debug Analysis 检查。

已知限制

• 叠片、近似叠片、局部片距不稳定、分隔条缺失、连续画面内容等困难场景仍可能误识别。
• 对不确定图片，请使用 Debug Analysis dry run，并人工复核。

文件校验

• Package: X5-Crop-v4.0.zip
• SHA256: 400341479f53da639262f1c521fba17d3fb259a7562ca32fca964cc1c6f4630b

English

V4.0 is the current stable release. The source code has been rewritten into the modular V4 architecture, while the Release package still ships a standalone X5_Crop.py so normal users only need the script and platform launcher.

Download X5-Crop-v4.0.zip from Assets on this page. Do not use GitHub's auto-generated Source code zip; that is the development source layout, not the prepared user package.

Original TIFF files are not modified. Auto crops are written as new files; files copied into needs_review/ are original-file copies for manual handling.

Quick Start

1. Unzip X5-Crop-v4.0.zip.
2. On first use, run the installer launcher:
   • macOS: double-click install/X5_Crop_Mac_install.command
   • Windows: double-click install\X5_Crop_win_install.bat
3. After installation, place X5_Crop.py, the platform main launcher, and your long TIFF scans in the same folder:
   • macOS main launcher: X5_Crop_Mac.command
   • Windows main launcher: X5_Crop_win.bat
4. Double-click the main launcher and choose the film format, partial mode, and Debug Analysis options.

Package Contents

X5_Crop.py
X5_Crop_Mac.command
X5_Crop_win.bat
README.txt
快速启动_Quick_Start.txt
install/
  X5_Crop_Mac_install.command
  X5_Crop_win_install.bat
  X5_Crop_Mac_uninstall.command
  X5_Crop_win_uninstall.bat

The Release X5_Crop.py is a standalone file with the internal x5crop/ code embedded. Normal users do not need to copy an x5crop/ folder.

V4.0 Highlights

• Modular V4 architecture: detection, geometry, evidence cache, TIFF I/O, Debug Analysis, report reuse, deskew, CLI, and regression now live in dedicated x5crop/ modules.
• Simple Release package: standalone script, two main launchers, two installers, two uninstallers, README, and quick-start guide.
• Full 135 default-deskew dry run against V3.9: 0 diffs for status, confidence, review_reasons, outer_box, frame_boxes, and gaps.
• Compared with the V3.6.2 stable release, V4 keeps later conservative improvements, including lucky-pass risk review gating and more stable red-gap / outer paths in known cases.
• Default output bleed: 20px on the long axis and 10px on the short axis. When overlap, near-overlap, or continuous-content risk is detected, long-axis output bleed is automatically raised to 50px. Bleed affects output only, not detection scoring.
• Documentation now states explicitly that auto-cropped TIFF output preserves source-TIFF quality-related attributes, including bit depth, channel layout, ICC / color space, resolution, and metadata. Cropping does not intentionally lower bit depth, recolor, compress, or resample image data.
• User documents inside the Release package now ship as README.txt and 快速启动_Quick_Start.txt for easier reading across systems. Repository source documents remain Markdown files.
• Cleaner documentation structure: README is now the full user manual and no longer repeats quick-start steps or changelog-style version notes; quick operation steps live in 快速启动_Quick_Start.md, and version differences live in CHANGELOG.md.
• This version is primarily optimized and regression-tested for normal 135 scans. Other formats are available, but Debug Analysis is recommended.

Known Limitations

• Overlap, near-overlap, locally irregular spacing, missing separators, and continuous image content can still be misdetected.
• Use Debug Analysis dry run and manually review uncertain scans.

Verification

• Package: X5-Crop-v4.0.zip
• SHA256: 400341479f53da639262f1c521fba17d3fb259a7562ca32fca964cc1c6f4630b

X5 Crop v3.6.2

中文快速使用

1. 下载并解压 X5-Crop-v3.6.2.zip。
2. 第一次使用先运行安装器：
   • macOS: install/X5_Crop_Mac_install.command
   • Windows: install\X5_Crop_win_install.bat
3. 把 X5_Crop.py、对应系统启动器和要裁切的 TIFF 长图放在同一个文件夹里。
4. 双击启动器，先选择 format，再选择是否 partial，再选择是否 Debug Analysis。

请下载本页面 Assets 里的 X5-Crop-v3.6.2.zip，不要下载 GitHub 自动生成的 Source code / 源码压缩包给普通用户使用。源码包是开发结构，不是整理好的用户发布包。

脚本不会修改原始 TIFF。自动裁切会生成新文件；进入 needs_review/ 的文件也是原 TIFF 的复制粘贴，方便人工处理。

English Quick Start

1. Download and unzip X5-Crop-v3.6.2.zip.
2. On a new machine, run the installer first:
   • macOS: install/X5_Crop_Mac_install.command
   • Windows: install\X5_Crop_win_install.bat
3. Put X5_Crop.py, the launcher for your OS, and the TIFF strip scans in the same folder.
4. Double-click the launcher, choose format, choose partial mode, then choose Debug Analysis.

Download X5-Crop-v3.6.2.zip from this page's Assets. Do not give normal users the auto-generated GitHub Source code zip; that is the development source layout, not the prepared user package.

The script does not modify original TIFF files. Auto crops are written as new files; files in needs_review/ are plain copies of the source TIFFs for manual handling.

包内文件 / Package Contents

X5_Crop.py
X5_Crop_Mac.command
X5_Crop_win.bat
README.md
快速启动_Quick_Start.md
install/
  X5_Crop_Mac_install.command
  X5_Crop_win_install.bat
  X5_Crop_Mac_uninstall.command
  X5_Crop_win_uninstall.bat

X5_Crop.py 是单文件脚本。日常使用只需要把 X5_Crop.py 和对应系统启动器复制到 TIFF 文件夹。

X5_Crop.py is a single-file script. For normal use, copy only X5_Crop.py and the platform launcher into the TIFF folder.

V3.6.2 稳定版说明

V3.6.2 是当前推荐给普通用户使用的稳定发布版。它保留 V3.3.1/V3.6 系列较稳定的检测链路，并完成了低收益逻辑清理：

• equal-broad-region 合并为普通 equal，Debug Analysis 和报告更容易读。
• hard_fallback_detection 缩小为 review-only fallback，避免 fallback 被误解成自动通过路径。
• 普通启动器不会开启 diagnostics；诊断能力保留给本地测试和开发分析。
• 输出 bleed 仍然只影响最终输出，不参与检测评分。

重要限制：叠片、近似叠片、局部片距非常不稳定、分隔条缺失或画面内容连续的长图，仍可能出现误识别或不够准确的裁切。遇到这些情况，请优先运行 Debug Analysis，并人工复核裁切框；不要把这类困难图当作完全可靠的自动裁切结果。

V3.6.2 Stable Release Notes

V3.6.2 is the current stable release recommended for normal users. It keeps the relatively stable V3.3.1/V3.6 detection chain and cleans up low-value logic:

• equal-broad-region is folded into ordinary equal, making Debug Analysis and reports easier to read.
• hard_fallback_detection is reduced to a review-only fallback so fallback logic is not mistaken for an auto-pass path.
• Normal launchers do not enable diagnostics; diagnostics remain available for local testing and development analysis.
• Output bleed still applies only to final output and does not participate in detection scoring.

Important limitation: overlapped frames, near-overlap, highly irregular local frame spacing, missing separator bars, or continuous image content can still be misdetected or cropped inaccurately. For these difficult scans, run Debug Analysis first and review crop boxes manually; do not treat them as fully reliable automatic crops.

Asset

• Package: X5-Crop-v3.6.2.zip
• SHA256: e01ed0f7e6661690c94d29d8e1c5d18987afa256baf4fd06267587d8188c85dc

X5 Crop v3.3.1

X5 Crop v3.3.1

快速使用

普通使用请下载本 Release 里的稳定版压缩包：

• X5-Crop-v3.3.1.zip

第一次在新机器上使用：

1. 下载并解压 X5-Crop-v3.3.1.zip。
2. 运行安装启动器：
   • macOS: install/X5_Crop_Mac_install.command
   • Windows: install/X5_Crop_win_install.bat
3. 把下面这些文件和要裁切的 TIFF 长图放在同一个文件夹里：
   • X5_Crop.py
   • macOS 用 X5_Crop_Mac.command
   • Windows 用 X5_Crop_win.bat
4. 双击对应系统的启动器。
5. 先选择胶片格式，再选择是否开启 partial mode 和 Debug Analysis。

常用选择：

• 直接回车或输入 135：普通 135，一条 6 张。
• 输入 dual 或 135 dual：双条 135，一共 12 张。
• 输入 xpan / half / 645 / 66 / 67：对应其它格式。
• partial mode 直接回车是 no，只在片头、片尾或不完整片条时开启。
• debug analysis 直接回车是 no；输入 y 会只生成分析 JPG 和报告，不正式裁切。

运行耗时：

• 在当前测试机器和常见 135 TIFF 长图上，普通 dry run / 裁切通常每张约 5-15 秒。
• Debug Analysis 需要额外生成 JPG 分析图，通常每张约 10-30 秒。
• 大尺寸 TIFF、开启 deskew、较慢硬盘或较慢电脑都会更久。
• 终端在处理单张大 TIFF 时可能一段时间没有新的提示；这通常不是出错，而是脚本还在读取、检测、校平或写文件。等它进入下一张图或完成当前图后会继续输出状态。

高置信结果会自动裁切；低置信结果会进入 needs_review/，方便人工复核。

Quick Start

For normal use, download the stable zip package from this Release:

• X5-Crop-v3.3.1.zip

On a new machine:

1. Download and unzip X5-Crop-v3.3.1.zip.
2. Run the installer launcher:
   • macOS: install/X5_Crop_Mac_install.command
   • Windows: install/X5_Crop_win_install.bat
3. Put these files in the same folder as the TIFF long-strip scans:
   • X5_Crop.py
   • macOS: X5_Crop_Mac.command
   • Windows: X5_Crop_win.bat
4. Double-click the launcher for your system.
5. Choose the film format, then choose whether to enable partial mode and Debug Analysis.

Common choices:

• Press Return or type 135: normal 135, 6 frames per strip.
• Type dual or 135 dual: dual-strip 135, 12 frames total.
• Type xpan / half / 645 / 66 / 67: other supported formats.
• Press Return for partial mode to choose no; enable it only for leader, tail, or incomplete strips.
• Press Return for debug analysis to choose no; type y to generate only analysis JPGs and reports without exporting cropped TIFFs.

Runtime:

• On the current test machine with typical 135 TIFF long-strip scans, normal dry run / export usually takes about 5-15 seconds per file.
• Debug Analysis also writes JPG analysis images and usually takes about 10-30 seconds per file.
• Very large TIFFs, deskew, slower disks, or slower computers can take longer.
• The terminal may show no new message for a while while one large TIFF is being read, detected, deskewed, or written. This usually does not mean the script has failed; it is still running and will print the next status line after the current file advances or finishes.

High-confidence results are cropped automatically. Low-confidence results go to needs_review/ for manual review.

稳定版说明 / Stable Release Note

普通用户建议下载 Release 压缩包。仓库 main 分支可能包含更新的开发进度，适合测试最新检测逻辑，但不一定是稳定发布版。

For normal use, download the Release zip package. The repository main branch may contain newer development work for testing the latest detection logic, but it is not necessarily the stable release.

相比上一版 v3 的主要变化

• 保留 V3 系列较稳定的 outer / gap / candidate 主检测链路，继续坚持只有高置信结果才自动裁切。
• 将 bleed 从检测评分中分离：bleed 只影响最终输出、报告和 Debug Analysis 色块，不参与 outer、gap、confidence 或 PASS/REVIEW。
• 默认输出 bleed 为长轴 20px、短轴 10px，并自动对应横向 / 竖向长图方向。
• 增加 PASS 后的轻量长轴输出保护，减少首尾画幅被同画幅拟合向内收得过多的情况；这不改变置信度或 PASS/REVIEW。
• 保留弱分隔、片距异常、近似叠片、内容证据冲突等情况进入复核的保守流程。
• Debug Analysis 输出 JPG 四联图，包含原始灰度图、Debug boxes、Separator evidence 和 Content evidence。
• 支持先跑 Debug Analysis dry run，再复用报告里的裁切框进行正式导出；needs_review 会跳过。
• 简化 Mac / Windows 启动器，并提供用户级依赖安装启动器。
• README 改为中英双语用户文档，并加入 MIT License。

Main Changes Since Previous v3

• Keeps the stable V3-style outer / gap / candidate detection chain and preserves the rule that only high-confidence results are cropped automatically.
• Separates bleed from detection scoring. Bleed affects only final output, reports, and Debug Analysis boxes, not outer boxes, gaps, confidence, or PASS/REVIEW.
• Default output bleed is 20px on the long axis and 10px on the short axis, with horizontal / vertical strip handling applied automatically.
• Adds small PASS-only long-axis output protection to reduce inward shrink at first/last frames after same-frame fitting. This does not change confidence or PASS/REVIEW.
• Keeps weak separators, irregular spacing, overlap-like frames, and conflicting content evidence in the conservative review workflow.
• Debug Analysis writes JPG four-panel views: original gray, Debug boxes, Separator evidence, and Content evidence.
• Supports running Debug Analysis dry run first, then reusing report crop boxes for export. needs_review files are skipped.
• Simplifies Mac / Windows launchers and provides user-level dependency installers.
• README is now bilingual Chinese/English, and the project uses the MIT License.