yccstego 0.1.0__tar.gz

yccstego-0.1.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: yccstego
+Version: 0.1.0
+Summary: JPEG compression-domain nsF5 steganography on the Y (luma) channel of YCbCr with self-contained DCT+Huffman codec
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: Pillow
+
+# yccstego —— YCC(YCbCr) 亮度通道 nsF5 隐写工具
+
+在 JPEG 压缩域中对 YCbCr 的 **Y（亮度）通道量化 DCT 系数** 实施 nsF5 伴随式矩阵编码隐写。
+自实现标准 JPEG(DCT+量化+Huffman) 编解码，保证量化系数在“保存→解析”后逐位一致，
+从而实现压缩域无失真往返嵌入。
+
+## 安装
+```bash
+pip install -e .
+```
+
+## 用法（CLI）
+```bash
+# 嵌入（消息 UTF-8，中英文均可）
+yccstego embed in.png out.jpg -m "你好，ycc stego" -p 3 -k 口令
+# 消息超容量时按 UTF-8 安全截断（默认则报错）
+yccstego embed small.png out.jpg -m "很长很长的中文…" -p 3 -k 口令 --truncate
+# 解码
+yccstego extract out.jpg -p 3 -k 口令
+# 隐写分析
+yccstego analyze out.jpg
+```
+
+## 结构
+- `yccstego/color.py`  RGB↔YCbCr(BT.601) 与 4:2:0 子采样
+- `yccstego/dct.py`   8×8 分块 DCT/IDCT、量化表、之字扫描
+- `yccstego/huffman.py` 标准 JPEG DC/AC Huffman 编解码
+- `yccstego/jpeg_codec.py` 图像↔量化系数↔.jpg 位流
+- `yccstego/nsf5.py`   Y 亮度量化 DCT 系数上的 nsF5 嵌入/提取(伴随式+湿纸+块置乱+图像哈希自同步)
+- `yccstego/steganalysis.py` YCC 域盲隐写分析
+- `yccstego/cli.py`   命令行入口

yccstego-0.1.0/README.md

@@ -0,0 +1,31 @@
+# yccstego —— YCC(YCbCr) 亮度通道 nsF5 隐写工具
+
+在 JPEG 压缩域中对 YCbCr 的 **Y（亮度）通道量化 DCT 系数** 实施 nsF5 伴随式矩阵编码隐写。
+自实现标准 JPEG(DCT+量化+Huffman) 编解码，保证量化系数在“保存→解析”后逐位一致，
+从而实现压缩域无失真往返嵌入。
+
+## 安装
+```bash
+pip install -e .
+```
+
+## 用法（CLI）
+```bash
+# 嵌入（消息 UTF-8，中英文均可）
+yccstego embed in.png out.jpg -m "你好，ycc stego" -p 3 -k 口令
+# 消息超容量时按 UTF-8 安全截断（默认则报错）
+yccstego embed small.png out.jpg -m "很长很长的中文…" -p 3 -k 口令 --truncate
+# 解码
+yccstego extract out.jpg -p 3 -k 口令
+# 隐写分析
+yccstego analyze out.jpg
+```
+
+## 结构
+- `yccstego/color.py`  RGB↔YCbCr(BT.601) 与 4:2:0 子采样
+- `yccstego/dct.py`   8×8 分块 DCT/IDCT、量化表、之字扫描
+- `yccstego/huffman.py` 标准 JPEG DC/AC Huffman 编解码
+- `yccstego/jpeg_codec.py` 图像↔量化系数↔.jpg 位流
+- `yccstego/nsf5.py`   Y 亮度量化 DCT 系数上的 nsF5 嵌入/提取(伴随式+湿纸+块置乱+图像哈希自同步)
+- `yccstego/steganalysis.py` YCC 域盲隐写分析
+- `yccstego/cli.py`   命令行入口

yccstego-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "yccstego"
+version = "0.1.0"
+description = "JPEG compression-domain nsF5 steganography on the Y (luma) channel of YCbCr with self-contained DCT+Huffman codec"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["numpy", "Pillow"]
+
+[project.scripts]
+yccstego = "yccstego.cli:main"
+
+[tool.setuptools]
+packages = ["yccstego"]

yccstego-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

yccstego-0.1.0/tests/test_codec.py

@@ -0,0 +1,120 @@
+"""JPEG-DCT 编解码(BT.601 YCbCr / 量化 / 之字 / Huffman 熵编码)单元测试。
+
+覆盖:
+- YCC 全流程往返: 量化系数逐位一致
+- 熵编码跨实现兼容: 自产 .jpg 能被 Pillow/libjpeg 解码
+- ZRL(≥16连续零)场景
+- DC 类别的合法边界(标准 DC 亮度表最大类别 11, |DC|<=2047)
+"""
+import os
+import sys
+import unittest
+
+import numpy as np
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from yccstego import jpeg_codec as J
+from yccstego import color, dct, huffman as H
+from yccstego.jpeg_codec import _encode_blocks, _decode_n, _cat_mag
+from yccstego.huffman import BitReader
+
+
+def make_rgb(h, w, seed=1, rng_np=np.random.RandomState):
+    rng = rng_np(seed)
+    x = np.linspace(0, 1, w)[None, :]
+    y = np.linspace(0, 1, h)[:, None]
+    base = np.sin(3 * x) * np.cos(5 * y) * 60 + 120
+    R = np.clip(base + 3 * x * 255 + rng.normal(0, 8, (h, w)), 0, 255).astype(np.uint8)
+    G = np.clip(120 + 60 * np.sin(8 * x) * np.exp(-(y - 0.5) ** 2 * 20)
+                + rng.normal(0, 8, (h, w)), 0, 255).astype(np.uint8)
+    B = np.clip(base - 40 * x + rng.normal(0, 8, (h, w)), 0, 255).astype(np.uint8)
+    return np.stack([R, G, B], axis=-1)
+
+
+def _entropy_roundtrip(blocks):
+    """编码->解码后量化块逐位一致。blocks:(nb,8,8) int16。"""
+    nb = blocks.shape[0]
+    data = _encode_blocks(blocks)
+    back = _decode_n(BitReader(data), nb, H.DC_TABLE, H.AC_TABLE)
+    expect = dct.zigzag(blocks).reshape(nb, 64)
+    return np.array_equal(expect, back), expect, back
+
+
+class TestJPEGRoundtrip(unittest.TestCase):
+    def test_ycc_roundtrip_bitwise(self):
+        for q in (70, 85, 95):
+            rgb = make_rgb(96, 128, seed=q)
+            ycc = J.YCC(rgb, quality=q)
+            back = J.YCC.from_bytes(ycc.to_bytes())
+            self.assertTrue(np.array_equal(ycc.Y, back.Y), f"Y mismatch q={q}")
+            self.assertTrue(np.array_equal(ycc.Cb, back.Cb), f"Cb mismatch q={q}")
+            self.assertTrue(np.array_equal(ycc.Cr, back.Cr), f"Cr mismatch q={q}")
+
+    def test_pillow_decodes_our_jpg(self):
+        from PIL import Image
+        import tempfile
+        rgb = make_rgb(48, 64, seed=5)
+        ycc = J.YCC(rgb, quality=85)
+        with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as f:
+            f.write(ycc.to_bytes())
+            path = f.name
+        try:
+            im = Image.open(path)
+            im.load()
+            self.assertEqual(im.size, (64, 48))
+        finally:
+            os.unlink(path)
+
+    def test_reconstruct_shape(self):
+        rgb = make_rgb(80, 96, seed=7)
+        ycc = J.YCC(rgb, quality=85)
+        pre = ycc.reconstruct()
+        self.assertEqual(pre.shape, rgb.shape)
+
+    def test_quality_scales_capacity(self):
+        rgb = make_rgb(64, 64, seed=9)
+        nz70 = np.count_nonzero(J.YCC(rgb, 70).Y)
+        nz95 = np.count_nonzero(J.YCC(rgb, 95).Y)
+        self.assertGreater(nz95, nz70)
+
+
+class TestEntropyCoding(unittest.TestCase):
+    def test_random_dc_valid_range(self):
+        # 差分编码: 每步 DC 差值须落在标准 DC 亮度表类别范围内(|diff|<=2047 => 类别<=11)。
+        # 相邻块的 DC 差即 Huffman 差分编码量, 直接以合法差值随机游走生成。
+        rng = np.random.RandomState(0)
+        for trial in range(5):
+            nb = 3 * (trial + 1)
+            blk = np.zeros((nb, 8, 8), dtype=np.int16)
+            prev = 0
+            for i in range(nb):
+                step = int(rng.randint(-1500, 1501))
+                dc = prev + step
+                dc = int(np.clip(dc, -2047, 2047))
+                blk[i, 0, 0] = dc
+                prev = dc
+                for _ in range(rng.randint(0, 8)):
+                    k = rng.randint(1, 64)
+                    blk[i, k // 8, k % 8] = rng.choice([-7, -5, -3, -1, 1, 2, 3, 5])
+            ok, _, _ = _entropy_roundtrip(blk)
+            self.assertTrue(ok, f"entropy roundtrip mismatch trial {trial}")
+
+    def test_zrl_long_runs(self):
+        for zeros in (16, 17, 20, 31, 40):
+            blk = np.zeros((1, 8, 8), dtype=np.int16)
+            blk[0, 0, 0] = 100
+            idx = 1 + zeros
+            blk[0, idx // 8, idx % 8] = 3
+            ok, _, _ = _entropy_roundtrip(blk)
+            self.assertTrue(ok, f"ZRL={zeros} roundtrip mismatch")
+
+    def test_cat_mag_boundaries(self):
+        # DC 类别边界: 1024..2047 → 类别11; 2048 不合法(无类别12)
+        self.assertEqual(_cat_mag(1024)[0], 11)
+        self.assertEqual(_cat_mag(2047)[0], 11)
+        self.assertEqual(_cat_mag(1)[0], 1)
+        self.assertEqual(_cat_mag(0)[0], 0)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

yccstego-0.1.0/tests/test_nsf5.py

@@ -0,0 +1,164 @@
+"""Y 域 nsF5 往返/篡改检测测试。独立可运行（python tests/test_nsf5.py），也兼容 pytest。"""
+import os, sys, numpy as np
+import contextlib
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from yccstego import jpeg_codec as J
+from yccstego import nsf5
+
+try:
+    import pytest
+    parametrize = pytest.mark.parametrize
+    raises = pytest.raises
+    _RUNNER = "pytest"
+except Exception:                       # 非 pytest 环境：自行驱动
+    def _parametrize(argnames, argvalues):
+        def deco(fn):
+            fn._params = (argnames, argvalues); return fn
+        return deco
+    def _raises(exc):
+        return contextlib.nullcontext() if exc is None else pytest_raises(exc)
+    class _Raises:
+        def __init__(self, exc): self.exc = exc; self.value = None
+        def __enter__(self):
+            class C:
+                def __exit__(self_, et, ev, tb):
+                    assert et and issubclass(et, self.exc), f"expected {self.exc}, got {et}"
+                    self.value = ev; return True
+            return C()
+        def __exit__(self, *a): pass
+    def pytest_raises(exc): return _Raises(exc)
+    parametrize = _parametrize
+    raises = _raises
+    _RUNNER = "manual"
+
+
+def make_rgb(h=96, w=128, seed=1):
+    rng = np.random.default_rng(seed)
+    x = np.linspace(0, 1, w)[None, :]
+    yy = np.linspace(0, 1, h)[:, None]
+    base = np.sin(3 * x) * np.cos(5 * yy) * 60 + 120
+    R = np.clip(base + 3 * x * 255 * np.random.uniform(0.5, 1.5, (h, w)), 0, 255)
+    G = np.clip(120 + 60 * np.sin(8 * x) * np.exp(-(yy - 0.5) ** 2 * 20) + rng.normal(0, 8, (h, w)), 0, 255)
+    B = np.clip(base - 40 * x + rng.normal(0, 8, (h, w)), 0, 255)
+    return np.stack([R, G, B], -1).astype(np.uint8)
+
+
+def embed_roundtrip(msg, p, password, rgb=None):
+    rgb = rgb if rgb is not None else make_rgb(128, 160)
+    c0 = J.YCC(rgb, 85)
+    y_new, rep = nsf5.embed_into_y(c0.Y, c0.Cb, c0.Cr, msg, p=p, password=password)
+    c1 = J.YCC.__new__(J.YCC)
+    c1.h, c1.w, c1.orig_shape, c1.quality = c0.h, c0.w, c0.orig_shape, 85
+    c1.qlum, c1.qchr = c0.qlum, c0.qchr
+    c1.Y, c1.Cb, c1.Cr = y_new, c0.Cb, c0.Cr
+    return J.YCC.from_bytes(c1.to_bytes()), rep     # 压缩域无失真往返
+
+
+P_LIST = [1, 2, 3, 4]
+MSG = ("Hello YCC nsF5 roundtrip 0123456789 abcdef ") * 2
+
+
+def test_roundtrip_ascii(p=3):
+    back, rep = embed_roundtrip(MSG, p, "pw")
+    out, cov, tampered, hm = nsf5.extract_from_y(back.Y, back.Cb, back.Cr, p=p, password="pw")
+    assert out == MSG, f"p={p} message mismatch"
+    assert tampered is False
+    assert hm is True
+
+
+CHN = ("中文隐写测试 YCC 亮度通道 携秘密 123456 " * 2).strip()
+
+
+def test_roundtrip_chinese():
+    for p in (1, 2, 3, 4):
+        back, rep = embed_roundtrip(CHN, p, "pw")
+        out, cov, tampered, hm = nsf5.extract_from_y(back.Y, back.Cb, back.Cr, p=p, password="pw")
+        assert out == CHN, f"p={p} Chinese message mismatch"
+        assert hm is True and tampered is False
+
+
+def test_wrong_password_fails():
+    back, _ = embed_roundtrip("secret-message", 3, "pw-a")
+    out, *_ = nsf5.extract_from_y(back.Y, back.Cb, back.Cr, p=3, password="pw-b")
+    assert out is None
+
+
+def test_chroma_tamper_detected():
+    c0 = J.YCC(make_rgb(128, 160), 85)
+    y_new, _ = nsf5.embed_into_y(c0.Y, c0.Cb, c0.Cr, "hello", p=3, password="pw")
+    bad_cb = c0.Cb.copy(); bad_cb.reshape(-1)[7] += 1
+    _, _, tampered, hm = nsf5.extract_from_y(y_new, bad_cb, c0.Cr, p=3, password="pw")
+    assert hm is False and tampered is True
+
+
+def test_y_body_tamper_detected():
+    c0 = J.YCC(make_rgb(128, 160), 85)
+    y_new, _ = nsf5.embed_into_y(c0.Y, c0.Cb, c0.Cr, "hello", p=3, password="pw")
+    bad = y_new.copy(); bad.reshape(-1)[80] += 1
+    out, *_ = nsf5.extract_from_y(bad, c0.Cb, c0.Cr, p=3, password="pw")
+    assert out is None
+
+
+def test_capacity_error():
+    rgb = make_rgb(16, 16)
+    c0 = J.YCC(rgb, 85)
+    try:
+        nsf5.embed_into_y(c0.Y, c0.Cb, c0.Cr, "x" * 5000, p=3, password="pw")
+        raise AssertionError("expected CapacityError")
+    except nsf5.CapacityError:
+        pass
+
+
+def test_truncate_over_capacity():
+    rgb = make_rgb(64, 64)      # 有头部池与少量正文池，但放不下超长中文
+    c0 = J.YCC(rgb, 85)
+    long_msg = ("中文隐写消息，长度远超这张图能容纳的载荷容量，测试 UTF-8 安全截断行为，"
+                "确保不会产生半个汉字，" * 10)
+    y, rep = nsf5.embed_into_y(c0.Y, c0.Cb, c0.Cr, long_msg, p=3, password="pw",
+                               truncate=True)
+    assert rep["truncated"] is True
+    assert 0 < rep["embedded_chars"] < len(long_msg)
+    # 截断结果必须能原样往返提取，且是原消息的合法 UTF-8 前缀
+    out, cov, tampered, hm = nsf5.extract_from_y(y, c0.Cb, c0.Cr, p=3, password="pw")
+    assert hm is True and tampered is False
+    assert long_msg.startswith(out)
+
+    # 超容量但未开 truncate 仍然抛错
+    try:
+        nsf5.embed_into_y(c0.Y, c0.Cb, c0.Cr, long_msg, p=3, password="pw", truncate=False)
+        raise AssertionError("expected CapacityError when truncate=False")
+    except nsf5.CapacityError:
+        pass
+
+
+def test_truncate_noop_within_capacity():
+    c0 = J.YCC(make_rgb(128, 160), 85)
+    y, rep = nsf5.embed_into_y(c0.Y, c0.Cb, c0.Cr, CHN, p=3, password="pw", truncate=True)
+    assert rep["truncated"] is False  # 容量足够，不应截断
+
+
+def _main():
+    failures = 0
+    for p in P_LIST:
+        try:
+            test_roundtrip_ascii(p); print(f"PASS test_roundtrip_ascii p={p}")
+        except AssertionError as e:
+            failures += 1; print(f"FAIL test_roundtrip_ascii p={p}: {e}")
+    try:
+        test_roundtrip_chinese(); print("PASS test_roundtrip_chinese")
+    except Exception as e:
+        failures += 1; print(f"FAIL test_roundtrip_chinese: {e!r}")
+    for name in ["test_wrong_password_fails", "test_chroma_tamper_detected",
+                 "test_y_body_tamper_detected", "test_capacity_error",
+                 "test_truncate_over_capacity", "test_truncate_noop_within_capacity"]:
+        try:
+            globals()[name](); print(f"PASS {name}")
+        except Exception as e:
+            failures += 1; print(f"FAIL {name}: {e!r}")
+    print("FAILURES:", failures)
+    sys.exit(1 if failures else 0)
+
+
+if __name__ == "__main__":
+    _main()

yccstego-0.1.0/yccstego/__init__.py

@@ -0,0 +1,7 @@
+"""yccstego —— JPEG 压缩域(YCbCr 亮度) nsF5 隐写工具。"""
+from .jpeg_codec import YCC
+from . import color, dct, huffman, jpeg_codec, nsf5, steganalysis, api
+
+__all__ = ["YCC", "color", "dct", "huffman", "jpeg_codec", "nsf5",
+           "steganalysis", "api"]
+__version__ = "0.1.0"

yccstego-0.1.0/yccstego/api.py

@@ -0,0 +1,66 @@
+"""面向文件/数组的高层 API：嵌入、提取、分析。
+
+流程：RGB → YCC（DCT+量化+Huffman 压缩到 .jpg 位流）→ 在量化 Y 的
+非零 AC 系数上做 nsF5 伴随式嵌入 → 写回位流；提取端解析位流回到量化系数再取消息。
+由于压缩域往返是"逐位一致"的（见 jpeg_codec），嵌入系数在文件往返后保持不变。
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from . import jpeg_codec as J
+from . import nsf5
+from . import steganalysis as S
+
+
+def _as_rgb(image) -> np.ndarray:
+    if isinstance(image, np.ndarray):
+        a = image
+    elif isinstance(image, (bytes, bytearray)):
+        from PIL import Image
+        import io
+        a = np.asarray(Image.open(io.BytesIO(bytes(image))).convert("RGB"))
+    else:  # 假定是路径 / 兼容 Pillow 对象
+        from PIL import Image
+        a = np.asarray(Image.open(image).convert("RGB"))
+    return np.ascontiguousarray(a.astype(np.uint8))
+
+
+def embed_bytes(rgb_image, text: str, p: int = 3, password: str = "", quality: int = 85,
+                truncate: bool = False):
+    """在图像上嵌入任意文本（UTF-8，中英文均可），返回 (.jpg bytes, report)。
+
+    rgb_image 支持 ndarray / bytes / 路径 / Pillow 对象。返回的字节是带隐写载荷的
+    标准 JPEG（libjpeg/Pillow 可打开），从位流本身也可无损还原嵌入系数。
+    消息超出容量时：truncate=False 抛 CapacityError；truncate=True 安全截断。
+    """
+    rgb = _as_rgb(rgb_image)
+    c0 = J.YCC(rgb, quality)
+    y_new, rep = nsf5.embed_into_y(c0.Y, c0.Cb, c0.Cr, text, p=p, password=password,
+                                   truncate=truncate)
+    c1 = J.YCC.__new__(J.YCC)
+    c1.h, c1.w, c1.orig_shape, c1.quality = c0.h, c0.w, c0.orig_shape, quality
+    c1.qlum, c1.qchr = c0.qlum, c0.qchr
+    c1.Y, c1.Cb, c1.Cr = y_new, c0.Cb, c0.Cr
+    return c1.to_bytes(), rep
+
+
+def extract_bytes(jpg_bytes, p: int = 3, password: str = ""):
+    """从 .jpg 位流提取消息。返回 (message|None, cover_hash_hex, tampered, head_match)。"""
+    y = J.YCC.from_bytes(bytes(jpg_bytes))
+    return nsf5.extract_from_y(y.Y, y.Cb, y.Cr, p=p, password=password)
+
+
+def analyze_bytes(jpg_bytes, sensitivity="均衡", unit_baseline=None):
+    """对 .jpg 位流做盲隐写分析。返回像素域与 DCT 域两套结论的合并字典。"""
+    y = J.YCC.from_bytes(bytes(jpg_bytes))
+    dct = S.analyze_y(y.Y, sensitivity=sensitivity, unit_baseline=unit_baseline)
+    try:
+        pix = S.analyze(y.reconstruct(), sensitivity=sensitivity)
+    except Exception:
+        pix = None
+    out = dict(dct)
+    if pix:
+        out.update(pix_probability=pix["stego_probability"],
+                   pix_verdict=pix["verdict"], pix=pix)
+    return out

yccstego-0.1.0/yccstego/cli.py

@@ -0,0 +1,132 @@
+"""yccstego 命令行入口：embed / extract / analyze。
+
+例：
+    yccstego embed cover.png out.jpg -m "hello" -p 3 -k 口令
+    yccstego extract out.jpg -p 3 -k 口令
+    yccstego analyze out.jpg
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .steganalysis import _SENS
+
+
+def _out_jpg(path, data: bytes):
+    with open(path, "wb") as f:
+        f.write(data)
+
+
+def cmd_embed(args):
+    try:
+        jpg_bytes, rep = _embed_impl(args.infile, args.message, args.p, args.password,
+                                     args.quality, args.truncate)
+    except Exception as e:
+        print(f"[错误] {e}", file=sys.stderr); sys.exit(2)
+    _out_jpg(args.outfile, jpg_bytes)
+    print(f"已嵌入 → {args.outfile}  ({len(jpg_bytes)} 字节)")
+    print(f"  正文载体数：{rep['body_pool']}  画像哈希：{rep['cover_hash']}")
+    if rep.get("truncated"):
+        print(f"  提示：消息超容量，已按 UTF-8 安全截断为 {rep['embedded_chars']} 字符")
+    if args.json:
+        print(json.dumps({**rep, "outfile": args.outfile}, ensure_ascii=False))
+
+
+def _embed_impl(infile, message, p, password, quality, truncate=False):
+    from .api import embed_bytes
+    return embed_bytes(infile, message, p=p, password=password, quality=quality,
+                       truncate=truncate)
+
+
+def cmd_extract(args):
+    try:
+        msg, cov, tampered, head_match = _extract_impl(args.infile, args.p, args.password)
+    except Exception as e:
+        print(f"[错误] {e}", file=sys.stderr); sys.exit(2)
+    if msg is None:
+        print(f"提取失败：{'发现篡改' if tampered else '口令错误或非本工具生成'} "
+              f"(header哈希匹配={head_match})")
+        sys.exit(1)
+    print(f"解密消息：{msg}")
+    print(f"覆盖图像哈希：{cov}  篡改标记：{tampered}")
+    if args.json:
+        print(json.dumps({"message": msg, "cover_hash": cov, "tampered": tampered,
+                          "header_match": head_match}, ensure_ascii=False))
+
+
+def _extract_impl(infile, p, password):
+    from .api import extract_bytes
+    data = _read(infile)
+    return extract_bytes(data, p=p, password=password)
+
+
+def cmd_analyze(args):
+    try:
+        res = _analyze_impl(args.infile, args.sensitivity)
+    except Exception as e:
+        print(f"[错误] {e}", file=sys.stderr); sys.exit(2)
+    print(f"文件：{args.infile}  AC系数数：{res.get('n_ac')}")
+    print(f"  DCT 卡方 p 值    : {res.get('dct_chi2_pvalue')}")
+    print(f"  奇数幅值占比      : {res.get('parity_odd')}   (基线 {res.get('base_parity')})")
+    print(f"  DCT 隐写概率      : {res.get('stego_probability_dct'):.3f}")
+    print(f"  DCT 判定          : {res.get('verdict')}")
+    if res.get("pix_probability") is not None:
+        print(f"  [像素域佐证] 概率 : {res.get('pix_probability'):.3f}  判定：{res.get('pix_verdict')}")
+    if args.json:
+        print(json.dumps(res, ensure_ascii=False, default=str))
+
+
+def _analyze_impl(infile, sensitivity):
+    from .api import analyze_bytes
+    data = _read(infile)
+    return analyze_bytes(data, sensitivity=sensitivity)
+
+
+def _read(path) -> bytes:
+    with open(path, "rb") as f:
+        return f.read()
+
+
+def build_parser():
+    ap = argparse.ArgumentParser(prog="yccstego",
+                                 description="JPEG 压缩域(Y 亮度 DCT) nsF5 隐写工具")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    e = sub.add_parser("embed", help="向图像嵌入文本")
+    e.add_argument("infile", help="输入图像（png/jpg/...）")
+    e.add_argument("outfile", help="输出 .jpg")
+    e.add_argument("-m", "--message", required=True, help="要嵌入的文本（UTF-8，中英文均可）")
+    e.add_argument("-p", "--p", type=int, default=3, help="矩阵编码参数 p（1..8，默认3）")
+    e.add_argument("-k", "--password", default="", help="口令（可选）")
+    e.add_argument("-q", "--quality", type=int, default=85, help="JPEG 质量（1..100）")
+    e.add_argument("-t", "--truncate", action="store_true",
+                   help="消息超容量时按 UTF-8 安全截断（默认超容量则报错）")
+    e.add_argument("--json", action="store_true")
+    e.set_defaults(func=cmd_embed)
+
+    x = sub.add_parser("extract", help="从 .jpg 提取消息")
+    x.add_argument("infile", help="输入 .jpg")
+    x.add_argument("-p", "--p", type=int, default=3)
+    x.add_argument("-k", "--password", default="")
+    x.add_argument("--json", action="store_true")
+    x.set_defaults(func=cmd_extract)
+
+    a = sub.add_parser("analyze", help="盲隐写分析")
+    a.add_argument("infile", help="输入 .jpg")
+    a.add_argument("-s", "--sensitivity", choices=list(_SENS), default="均衡",
+                   help="判定灵敏度")
+    a.add_argument("--json", action="store_true")
+    a.set_defaults(func=cmd_analyze)
+    return ap
+
+
+def main(argv=None):
+    ap = build_parser()
+    args = ap.parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

yccstego-0.1.0/yccstego/color.py

@@ -0,0 +1,44 @@
+"""RGB <-> YCbCr(BT.601) 转换与 4:2:0 子采样。"""
+from __future__ import annotations
+
+import numpy as np
+
+# BT.601 full-swing 系数 (0..255)
+KR, KG, KB = 0.114, 0.587, 0.299
+
+
+def rgb2ycbcr(rgb: np.ndarray) -> np.ndarray:
+    """rgb: (H,W,3) uint8 -> ycbr: (H,W,3) float32 [0,255]。"""
+    R = rgb[..., 0].astype(np.float32)
+    G = rgb[..., 1].astype(np.float32)
+    B = rgb[..., 2].astype(np.float32)
+    Y = KR * R + KG * G + KB * B
+    Cb = 128.0 + (B - Y) * 0.564
+    Cr = 128.0 + (R - Y) * 0.713
+    return np.stack([Y, Cb, Cr], axis=-1)
+
+
+def ycbcr2rgb(ycc: np.ndarray) -> np.ndarray:
+    """ycc: (H,W,3) float -> rgb uint8 Clamped。"""
+    Y = ycc[..., 0].astype(np.float32)
+    Cb = ycc[..., 1].astype(np.float32) - 128.0
+    Cr = ycc[..., 2].astype(np.float32) - 128.0
+    R = Y + 1.402 * Cr
+    G = Y - 0.344136 * Cb - 0.714136 * Cr
+    B = Y + 1.772 * Cb
+    out = np.stack([R, G, B], axis=-1)
+    return np.clip(out, 0, 255).round().astype(np.uint8)
+
+
+def subsample(ch: np.ndarray, factor: int = 2) -> np.ndarray:
+    """4:2:0: 对单通道做 2x2 均值下采样。ch: (H,W) float。"""
+    H, W = ch.shape
+    Hs, Ws = H // factor, W // factor
+    ch = ch[: Hs * factor, : Ws * factor]
+    return 0.25 * (ch[::2, ::2] + ch[1::2, ::2] + ch[::2, 1::2] + ch[1::2, 1::2])
+
+
+def upsample(ch: np.ndarray, target: tuple, factor: int = 2) -> np.ndarray:
+    """最近邻放大回原尺寸。chn: (Hs,Ws)。"""
+    H, W = target
+    return np.repeat(np.repeat(ch, factor, axis=0), factor, axis=1)[:H, :W]