docvortex 0.2.1__py3-none-any.whl

docvortex/export/bundle.py

@@ -0,0 +1,98 @@
+"""保存及读取不依赖源文件、网络或宿主缓存的结果包。"""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from hashlib import sha256
+import json
+from pathlib import Path
+from typing import Any
+
+from ..assets import AssetStore
+from ..codecs.json import load_middle, load_model
+from ..foundation.image_payload import INLINE_IMAGE_DATA_URI_RE, parse_image_data_uri_strict
+from ..result import Diagnostic, DocumentResult, ExportResult
+from .files import materialize_middle, validate_materialized_assets
+from .middle import _commit_export_files, _resolve_export_target, _validate_export_path_relationships
+
+
+def _externalize_model(value: Any, assets: AssetStore) -> Any:
+    """在原始分析副本中外置图片及 HTML 内嵌素材，保持可独立重放。"""
+    if isinstance(value, list):
+        return [_externalize_model(item, assets) for item in value]
+    if isinstance(value, dict):
+        result = {key: _externalize_model(item, assets) for key, item in value.items()}
+        image = value.get("image_base64")
+        if isinstance(image, str):
+            result["image_path"] = _add_image(image, assets)
+            result.pop("image_base64", None)
+        return result
+    if isinstance(value, str) and "data:image/" in value and not value.startswith("data:image/"):
+        return INLINE_IMAGE_DATA_URI_RE.sub(lambda match: _add_image(match.group(0), assets), value)
+    return value
+
+
+def _add_image(data_uri: str, assets: AssetStore) -> str:
+    """按内容摘要登记分析阶段素材，避免产生不稳定文件名。"""
+    payload, extension = parse_image_data_uri_strict(data_uri)
+    path = f"images/{sha256(payload).hexdigest()}.{extension}"
+    assets.add(path, payload)
+    return path
+
+
+def save_bundle(result: DocumentResult, path: Path, *, overwrite: bool = False) -> ExportResult:
+    """将中间协议与素材清单放入同一文件事务。"""
+    middle, assets = materialize_middle(result.middle_json, result.assets)
+    validate_materialized_assets(middle, assets)
+    files: dict[str, bytes] = {"middle.json": middle.to_json(skip_defaults=False).encode("utf-8")}
+    manifest: dict[str, Any] = {
+        "schema": "docvortex.bundle",
+        "schema_version": "2.0",
+        "middle": "middle.json",
+        "diagnostics": [asdict(item) for item in result.diagnostics],
+    }
+    if result.model_json is not None:
+        model = _externalize_model(result.model_json.to_dict(skip_defaults=False), assets)
+        files["model.json"] = json.dumps(model, ensure_ascii=False, indent=2).encode("utf-8")
+        manifest["model"] = "model.json"
+    manifest["assets"] = [
+        {"path": name, "size": len(payload), "sha256": sha256(payload).hexdigest()} for name, payload in sorted(assets.items())
+    ]
+    if {"manifest.json", "middle.json", "model.json"}.intersection(assets):
+        raise ValueError("Bundle assets conflict with reserved document files")
+    files.update(assets)
+    files["manifest.json"] = json.dumps(manifest, ensure_ascii=False, indent=2).encode("utf-8")
+    _validate_export_path_relationships(list(files))
+    path = path.absolute()
+    _commit_export_files({_resolve_export_target(path, name): value for name, value in files.items()}, overwrite=overwrite)
+    return ExportResult(path / "manifest.json", tuple(path / name for name in assets))
+
+
+def load_bundle(path: str | Path) -> DocumentResult:
+    """校验结果包版本、路径及素材摘要后恢复可渲染结果。"""
+    root = Path(path).absolute()
+    manifest = json.loads(_resolve_export_target(root, "manifest.json").read_text(encoding="utf-8"))
+    if manifest.get("schema") != "docvortex.bundle" or manifest.get("schema_version") != "2.0":
+        raise ValueError("Unsupported DocVortex bundle schema")
+    if manifest.get("middle") != "middle.json" or manifest.get("model") not in {None, "model.json"}:
+        raise ValueError("Invalid bundle document paths")
+    assets = AssetStore()
+    for item in manifest["assets"]:
+        if item["path"] in {"manifest.json", "middle.json", "model.json"}:
+            raise ValueError("Bundle asset uses a reserved document path")
+        payload = _resolve_export_target(root, item["path"]).read_bytes()
+        if len(payload) != item["size"] or sha256(payload).hexdigest() != item["sha256"]:
+            raise ValueError(f"Bundle asset integrity mismatch: {item['path']}")
+        assets.add(item["path"], payload)
+    middle = load_middle(json.loads(_resolve_export_target(root, "middle.json").read_text(encoding="utf-8")))
+    validate_materialized_assets(middle, assets)
+    model = (
+        load_model(json.loads(_resolve_export_target(root, "model.json").read_text(encoding="utf-8")))
+        if manifest.get("model")
+        else None
+    )
+    diagnostics = tuple(Diagnostic(**item) for item in manifest.get("diagnostics", []))
+    return DocumentResult(middle_json=middle, assets=assets, model_json=model, diagnostics=diagnostics)
+
+
+__all__ = ["save_bundle", "load_bundle"]

docvortex/export/files.py

@@ -0,0 +1,66 @@
+"""独立渲染文件和文档素材的统一写出。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..assets import AssetStore
+from ..content.tree import iter_child_blocks
+from ..schema import MiddleJson
+from ..result import ExportResult, RenderArtifact
+from .middle import _commit_export_files, _prepare_export_copy, _resolve_export_target, _validate_export_path_relationships
+
+
+def materialize_middle(middle_json: MiddleJson, assets: AssetStore | None = None) -> tuple[MiddleJson, AssetStore]:
+    """在文档副本上外置所有内嵌图片，保留调用者提供的外部素材。"""
+    document, embedded = _prepare_export_copy(middle_json)
+    result = assets.copy() if assets is not None else AssetStore()
+    for path, payload in embedded.items():
+        result.add(path, payload)
+    pending = [block for page in document.pages for block in page.blocks]
+    while pending:
+        block = pending.pop()
+        pending.extend(iter_child_blocks(block))
+        image_path = getattr(block, "image_path", None)
+        if image_path and image_path in result and getattr(block, "image_url", None):
+            block.image_url = None
+    return document, result
+
+
+def validate_materialized_assets(middle_json: MiddleJson, assets: AssetStore) -> None:
+    """拒绝依赖外部文件或网络的未物化图片，保证结果包能离线重渲染。"""
+    from bs4 import BeautifulSoup
+
+    pending = [block for page in middle_json.pages for block in page.blocks]
+    while pending:
+        block = pending.pop()
+        pending.extend(iter_child_blocks(block))
+        image_path = getattr(block, "image_path", None)
+        if image_path and image_path not in assets:
+            raise ValueError(f"Missing materialized asset: {image_path}")
+        if getattr(block, "image_url", None) and not image_path:
+            raise ValueError("An external image must be materialized before saving a bundle")
+        content = getattr(block, "content", None)
+        if str(block.type) not in {"table_body", "chart_body", "image_body"} or not isinstance(content, str):
+            continue
+        if "<img" not in content.lower():
+            continue
+        for image in BeautifulSoup(content, "html.parser").find_all("img"):
+            reference = image.get("src")
+            if reference and reference not in assets:
+                raise ValueError(f"Missing materialized HTML image: {reference}")
+
+
+def write_artifact(artifact: RenderArtifact, path: Path, *, overwrite: bool) -> ExportResult:
+    """检查主文件与素材的路径关系后，以同一事务写出。"""
+    path = path.absolute()
+    relative_files = {path.name: artifact.content, **dict(artifact.assets)}
+    if path.name in artifact.assets:
+        raise ValueError("Main file conflicts with an asset")
+    _validate_export_path_relationships(list(relative_files))
+    targets = {_resolve_export_target(path.parent, name): payload for name, payload in relative_files.items()}
+    _commit_export_files(targets, overwrite=overwrite)
+    return ExportResult(path=path, asset_paths=tuple(path.parent / name for name in artifact.assets))
+
+
+__all__ = ["materialize_middle", "validate_materialized_assets", "write_artifact"]

docvortex/export/middle.py

@@ -0,0 +1,208 @@
+"""语义文档与图片旁文件的原子导出。"""
+
+from __future__ import annotations
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Any, Sequence
+from ..schema import MiddleJson, BlockBase, _iter_child_blocks
+
+
+@dataclass(frozen=True, slots=True)
+class MiddleJsonExportResult:
+    """Middle JSON 图片外置后的对象副本与实际文件路径。"""
+
+    middle_json: MiddleJson
+    json_path: Path
+    image_paths: tuple[Path, ...]
+
+
+def _iter_page_blocks(blocks: Sequence[BlockBase]) -> list[BlockBase]:
+    """按深度优先顺序展开页面 block 树，供图片外置统一遍历。"""
+    result: list[BlockBase] = []
+    pending: list[BlockBase] = list(reversed(blocks))
+    while pending:
+        block = pending.pop()
+        result.append(block)
+        pending.extend(reversed(_iter_child_blocks(block)))
+    return result
+
+
+def _register_export_file(files: dict[str, bytes], relative_path: str, payload: bytes) -> None:
+    """登记待写文件，并在同名内容冲突时立即终止导出。"""
+    existing = files.get(relative_path)
+    if existing is not None and existing != payload:
+        raise ValueError(f"Conflicting image payload for path: {relative_path}")
+    files[relative_path] = payload
+
+
+def _prepare_export_copy(middle_json: MiddleJson) -> tuple[MiddleJson, dict[str, bytes]]:
+    """复制对象、解析直接及 HTML 图片，并回填副本中的相对路径。"""
+    from ..foundation.image_payload import (
+        INLINE_IMAGE_DATA_URI_RE,
+        parse_image_data_uri_strict,
+    )
+
+    exported = middle_json.model_copy(deep=True)
+    image_files: dict[str, bytes] = {}
+    for page in exported.pages:
+        for block in _iter_page_blocks(page.blocks):
+            data_uri = getattr(block, "image_base64", None)
+            if data_uri is not None:
+                if block.index is None:
+                    raise ValueError(f"Image carrier requires index: page_idx={page.page_idx}, type={block.type}")
+                image_bytes, extension = parse_image_data_uri_strict(data_uri)
+                relative_path = f"images/page_{page.page_idx}_{block.type}_{block.index}.{extension}"
+                _register_export_file(image_files, relative_path, image_bytes)
+                block.image_path = relative_path  # type: ignore[attr-defined]
+                block.image_base64 = None  # type: ignore[attr-defined]
+
+            content = getattr(block, "content", None)
+            if not isinstance(content, str) or "data:image/" not in content:
+                continue
+            if block.index is None:
+                raise ValueError(f"HTML image carrier requires index: page_idx={page.page_idx}, type={block.type}")
+            ordinal = 0
+
+            def _replace_data_uri(match: Any) -> str:
+                """将当前 HTML data URI 登记为 sidecar，并返回确定性相对路径。"""
+                nonlocal ordinal
+                ordinal += 1
+                image_bytes, extension = parse_image_data_uri_strict(match.group(0))
+                relative_path = f"images/page_{page.page_idx}_{block.type}_{block.index}_{ordinal}.{extension}"
+                _register_export_file(image_files, relative_path, image_bytes)
+                return relative_path
+
+            block.content = INLINE_IMAGE_DATA_URI_RE.sub(_replace_data_uri, content)  # type: ignore[assignment]
+    return exported, image_files
+
+
+def _resolve_export_target(output_root: Path, relative_path: str) -> Path:
+    """校验导出相对路径并确保解析后的目标仍位于文档输出目录内。"""
+    from ..foundation.image_payload import validate_image_sidecar_path
+
+    safe_path = validate_image_sidecar_path(relative_path)
+    if output_root.is_symlink():
+        raise ValueError(f"Export directory must not be a symlink: {output_root}")
+    if output_root.exists() and not output_root.is_dir():
+        raise ValueError(f"Export directory must be a directory: {output_root}")
+    root = output_root.resolve()
+    target = root / safe_path
+    current_parent = root
+    for path_part in Path(safe_path).parts[:-1]:
+        current_parent /= path_part
+        if current_parent.is_symlink():
+            raise ValueError(f"Export path contains a symlink: {relative_path}")
+        if current_parent.exists() and not current_parent.is_dir():
+            raise ValueError(f"Export path parent is not a directory: {relative_path}")
+    try:
+        target.parent.resolve(strict=False).relative_to(root)
+    except ValueError as exc:
+        raise ValueError(f"Export path escapes output directory: {relative_path}") from exc
+    return target
+
+
+def _commit_export_files(files: dict[Path, bytes], *, overwrite: bool) -> None:
+    """预检冲突后以临时文件提交，并在提交失败时恢复已有文件。"""
+    pending: dict[Path, bytes] = {}
+    originals: dict[Path, bytes | None] = {}
+    for target, payload in files.items():
+        if target.is_symlink():
+            raise ValueError(f"Export target must not be a symlink: {target}")
+        if target.exists():
+            if not target.is_file():
+                raise ValueError(f"Export target is not a regular file: {target}")
+            current = target.read_bytes()
+            if current == payload:
+                continue
+            if not overwrite:
+                raise FileExistsError(f"Export target already exists with different content: {target}")
+            originals[target] = current
+        else:
+            originals[target] = None
+        pending[target] = payload
+
+    temp_paths: dict[Path, Path] = {}
+    committed: list[Path] = []
+    try:
+        for target, payload in pending.items():
+            target.parent.mkdir(parents=True, exist_ok=True)
+            with NamedTemporaryFile(
+                mode="wb",
+                prefix=".docvortex-export-",
+                dir=target.parent,
+                delete=False,
+            ) as temp_file:
+                temp_file.write(payload)
+                temp_paths[target] = Path(temp_file.name)
+        for target, temp_path in temp_paths.items():
+            os.replace(temp_path, target)
+            committed.append(target)
+    except Exception:
+        for temp_path in temp_paths.values():
+            temp_path.unlink(missing_ok=True)
+        for target in reversed(committed):
+            original = originals[target]
+            if original is None:
+                target.unlink(missing_ok=True)
+            else:
+                target.write_bytes(original)
+        raise
+
+
+def _validate_export_path_relationships(relative_paths: list[str]) -> None:
+    """拒绝任一导出文件占用另一文件的父目录，避免提交阶段才产生冲突。"""
+    path_parts = {relative_path: Path(relative_path).parts for relative_path in relative_paths}
+    for relative_path, parts in path_parts.items():
+        for other_path, other_parts in path_parts.items():
+            if relative_path == other_path or len(parts) >= len(other_parts):
+                continue
+            if other_parts[: len(parts)] == parts:
+                raise ValueError(f"Export file path conflicts with a required directory: {relative_path} -> {other_path}")
+
+
+def _export_middle_json(
+    middle_json: MiddleJson,
+    output_dir: Path,
+    *,
+    json_name: str,
+    overwrite: bool,
+) -> MiddleJsonExportResult:
+    """构造完整导出事务，保证 JSON 与图片使用同一份规范化对象副本。"""
+    from ..foundation.image_payload import validate_image_sidecar_path
+
+    exported, image_files = _prepare_export_copy(middle_json)
+    json_text = exported.to_json(
+        exclude_block_fields={"image_base64"},
+    )
+    if "data:image/" in json_text.lower():
+        raise ValueError("Exported Middle JSON still contains an inline image data URI")
+    json_bytes = json_text.encode("utf-8")
+    safe_json_name = validate_image_sidecar_path(json_name)
+    relative_files = dict(image_files)
+    if safe_json_name in relative_files:
+        raise ValueError(f"JSON path conflicts with an exported image: {safe_json_name}")
+    relative_files[safe_json_name] = json_bytes
+    _validate_export_path_relationships(list(relative_files))
+    absolute_files = {
+        _resolve_export_target(output_dir, relative_path): payload for relative_path, payload in relative_files.items()
+    }
+    _commit_export_files(absolute_files, overwrite=overwrite)
+    json_path = _resolve_export_target(output_dir, safe_json_name)
+    image_paths = tuple(_resolve_export_target(output_dir, relative_path) for relative_path in sorted(image_files))
+    return MiddleJsonExportResult(
+        middle_json=exported,
+        json_path=json_path,
+        image_paths=image_paths,
+    )
+
+
+def export_middle_json(
+    middle_json: MiddleJson, output_dir: str | Path, *, json_name: str = "middle_json.json", overwrite: bool = False
+) -> MiddleJsonExportResult:
+    """显式导出语义协议及图片，保持基础 schema 无文件系统依赖。"""
+    return _export_middle_json(middle_json, Path(output_dir), json_name=json_name, overwrite=overwrite)
+
+
+__all__ = ["MiddleJsonExportResult", "export_middle_json"]

docvortex/foundation/__init__.py

@@ -0,0 +1,3 @@
+"""DocVortex 模块边界。"""
+
+__all__ = []

docvortex/foundation/geometry.py

@@ -0,0 +1,125 @@
+import math
+
+import numpy as np
+
+from ..schema import BBox, IntBBox
+
+
+def normalize_to_int_bbox(
+    box: list[list[float]] | list[float] | BBox | None,
+    image_size: tuple[int, int] | None = None,
+) -> IntBBox | None:
+    if box is None:
+        return None
+
+    arr = np.asarray(box, dtype=np.float64)
+    if arr.size == 0:
+        return None
+
+    if arr.ndim == 2 and arr.shape[-1] == 2:
+        xs = arr[:, 0]
+        ys = arr[:, 1]
+        xmin = float(np.min(xs))
+        ymin = float(np.min(ys))
+        xmax = float(np.max(xs))
+        ymax = float(np.max(ys))
+    else:
+        flat = arr.reshape(-1)
+        if flat.size == 4:
+            xmin, ymin, xmax, ymax = [float(v) for v in flat]
+        elif flat.size >= 8:
+            xs = flat[0::2]
+            ys = flat[1::2]
+            xmin = float(np.min(xs))
+            ymin = float(np.min(ys))
+            xmax = float(np.max(xs))
+            ymax = float(np.max(ys))
+        else:
+            return None
+
+    xmin = math.floor(xmin)
+    ymin = math.floor(ymin)
+    xmax = math.ceil(xmax)
+    ymax = math.ceil(ymax)
+
+    if image_size is not None:
+        height, width = image_size
+        xmin = max(0, min(int(width), xmin))
+        ymin = max(0, min(int(height), ymin))
+        xmax = max(0, min(int(width), xmax))
+        ymax = max(0, min(int(height), ymax))
+
+    if xmax <= xmin or ymax <= ymin:
+        return None
+
+    return (int(xmin), int(ymin), int(xmax), int(ymax))
+
+
+def bbox_relative_pos(bbox1: BBox, bbox2: BBox) -> tuple[bool, bool, bool, bool]:
+    """返回 bbox1 相对 bbox2 的左、右、下、上位置关系。"""
+    x1, y1, x1b, y1b = bbox1
+    x2, y2, x2b, y2b = bbox2
+    left = x2b < x1
+    right = x1b < x2
+    bottom = y2b < y1
+    top = y1b < y2
+    return left, right, bottom, top
+
+
+def bbox_distance(bbox1: BBox, bbox2: BBox) -> float:
+    """计算两个不相交矩形之间的最短欧氏距离。"""
+    x1, y1, x1b, y1b = bbox1
+    x2, y2, x2b, y2b = bbox2
+    left, right, bottom, top = bbox_relative_pos(bbox1, bbox2)
+    if top and left:
+        return math.hypot(x1 - x2b, y1b - y2)
+    if left and bottom:
+        return math.hypot(x1 - x2b, y1 - y2b)
+    if bottom and right:
+        return math.hypot(x1b - x2, y1 - y2b)
+    if right and top:
+        return math.hypot(x1b - x2, y1b - y2)
+    if left:
+        return x1 - x2b
+    if right:
+        return x2 - x1b
+    if bottom:
+        return y1 - y2b
+    if top:
+        return y2 - y1b
+    return 0.0
+
+
+def bbox_center_distance(bbox1: BBox, bbox2: BBox) -> float:
+    """计算两个矩形中心点之间的欧氏距离。"""
+    center1 = ((bbox1[0] + bbox1[2]) / 2, (bbox1[1] + bbox1[3]) / 2)
+    center2 = ((bbox2[0] + bbox2[2]) / 2, (bbox2[1] + bbox2[3]) / 2)
+    return math.hypot(center1[0] - center2[0], center1[1] - center2[1])
+
+
+def calculate_overlap_area_2_minbox_area_ratio(bbox1: BBox, bbox2: BBox) -> float:
+    """计算交集面积占两个矩形较小面积的比例。"""
+    x_left = max(bbox1[0], bbox2[0])
+    y_top = max(bbox1[1], bbox2[1])
+    x_right = min(bbox1[2], bbox2[2])
+    y_bottom = min(bbox1[3], bbox2[3])
+    if x_right <= x_left or y_bottom <= y_top:
+        return 0.0
+    overlap = (x_right - x_left) * (y_bottom - y_top)
+    area1 = max(0.0, (bbox1[2] - bbox1[0]) * (bbox1[3] - bbox1[1]))
+    area2 = max(0.0, (bbox2[2] - bbox2[0]) * (bbox2[3] - bbox2[1]))
+    min_area = min(area1, area2)
+    return overlap / min_area if min_area > 0 else 0.0
+
+
+def calculate_overlap_area_in_bbox1_area_ratio(bbox1: BBox, bbox2: BBox) -> float:
+    """计算两个矩形交集面积占 bbox1 面积的比例。"""
+    x_left = max(bbox1[0], bbox2[0])
+    y_top = max(bbox1[1], bbox2[1])
+    x_right = min(bbox1[2], bbox2[2])
+    y_bottom = min(bbox1[3], bbox2[3])
+    if x_right <= x_left or y_bottom <= y_top:
+        return 0.0
+    overlap = (x_right - x_left) * (y_bottom - y_top)
+    area1 = max(0.0, (bbox1[2] - bbox1[0]) * (bbox1[3] - bbox1[1]))
+    return overlap / area1 if area1 > 0 else 0.0

docvortex/foundation/hyperlink.py

@@ -0,0 +1,65 @@
+"""不依赖解析器层的安全超链接目标校验。"""
+
+from __future__ import annotations
+
+from collections.abc import Collection
+from typing import Any, Final
+from urllib.parse import urlsplit
+
+
+DEFAULT_EXTERNAL_HYPERLINK_SCHEMES: Final = frozenset({"http", "https", "mailto", "tel"})
+OFFICE_EXTERNAL_HYPERLINK_SCHEMES: Final = DEFAULT_EXTERNAL_HYPERLINK_SCHEMES | {"ftp"}
+
+
+def sanitize_hyperlink_target(
+    value: Any,
+    *,
+    allowed_schemes: Collection[str] = DEFAULT_EXTERNAL_HYPERLINK_SCHEMES,
+    allow_relative: bool = False,
+    allow_fragment: bool = False,
+    allow_root_relative: bool = False,
+) -> str | None:
+    """按调用方策略保留安全外链、相对链接或文档内 fragment。"""
+    if value is None:
+        return None
+    normalized = str(value).strip()
+    if (
+        not normalized
+        or normalized == "."
+        or any(ord(char) < 0x20 or ord(char) == 0x7F or 0xD800 <= ord(char) <= 0xDFFF for char in normalized)
+        or any(char in normalized for char in ("<", ">", "\\"))
+        or normalized.startswith("//")
+    ):
+        return None
+    try:
+        parsed = urlsplit(normalized)
+    except ValueError:
+        return None
+    scheme = parsed.scheme.casefold()
+    allowed = {item.casefold() for item in allowed_schemes}
+    if scheme:
+        if scheme not in allowed:
+            return None
+        if scheme in {"http", "https", "ftp"}:
+            try:
+                if not parsed.netloc or parsed.hostname is None:
+                    return None
+            except ValueError:
+                return None
+        elif not parsed.path:
+            return None
+        return normalized
+    if parsed.netloc:
+        return None
+    if normalized.startswith("#"):
+        return normalized if allow_fragment and normalized[1:].strip() else None
+    if normalized.startswith("/") and not allow_root_relative:
+        return None
+    return normalized if allow_relative else None
+
+
+__all__ = [
+    "DEFAULT_EXTERNAL_HYPERLINK_SCHEMES",
+    "OFFICE_EXTERNAL_HYPERLINK_SCHEMES",
+    "sanitize_hyperlink_target",
+]

docvortex/foundation/image.py

@@ -0,0 +1,48 @@
+"""跨模型共享的轻量图像统计与裁剪原语。"""
+
+import cv2
+import numpy as np
+from PIL import Image
+
+from ..schema import BBox
+from .geometry import normalize_to_int_bbox
+
+
+def calculate_contrast(img: np.ndarray, img_mode: str) -> float:
+    """
+    计算给定图像的对比度。
+    :param img: 图像，类型为numpy.ndarray
+    :Param img_mode = 图像的色彩通道，'rgb' 或 'bgr'
+    :return: 图像的对比度值
+    """
+    if img_mode == "rgb":
+        # 将RGB图像转换为灰度图
+        gray_img = cv2.cvtColor(img, cv2.COLOR_RGB2GRAY)
+    elif img_mode == "bgr":
+        # 将BGR图像转换为灰度图
+        gray_img = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    else:
+        raise ValueError("Invalid image mode. Please provide 'rgb' or 'bgr'.")
+
+    # 计算均值和标准差
+    mean_value = np.mean(gray_img)
+    std_dev = np.std(gray_img)
+    # 对比度定义为标准差除以平均值（加上小常数避免除零错误）
+    contrast = std_dev / (mean_value + 1e-6)
+    # logger.debug(f"contrast: {contrast}")
+    return round(float(contrast), 2)
+
+
+def crop_pil_image(bbox: BBox, image: Image.Image) -> Image.Image:
+    """按 0-1 归一化 bbox 裁剪 Pillow 图像。"""
+    width, height = image.size
+    scaled_bbox = normalize_to_int_bbox(
+        [bbox[0] * width, bbox[1] * height, bbox[2] * width, bbox[3] * height],
+        image_size=(height, width),
+    )
+    if scaled_bbox is None:
+        return image.crop((0, 0, 0, 0))
+    return image.crop(scaled_bbox)
+
+
+__all__ = ["calculate_contrast", "crop_pil_image"]

docvortex/foundation/image_encoding.py

@@ -0,0 +1,30 @@
+"""Flash 各格式复用的轻量图片编码能力。"""
+
+from __future__ import annotations
+
+import base64
+from io import BytesIO
+
+from PIL import Image
+
+
+def image_to_bytes(
+    image: Image.Image,
+    image_format: str = "JPEG",
+) -> bytes:
+    """按指定格式把 Pillow 图片编码为字节。"""
+    with BytesIO() as image_buffer:
+        image.save(image_buffer, format=image_format)
+        return image_buffer.getvalue()
+
+
+def image_to_b64str(
+    image: Image.Image,
+    image_format: str = "JPEG",
+) -> str:
+    """按指定格式把 Pillow 图片编码为 data URI。"""
+    image_bytes = image_to_bytes(image, image_format)
+    return f"data:image/{image_format.lower()};base64,{base64.b64encode(image_bytes).decode('utf-8')}"
+
+
+__all__ = ["image_to_b64str", "image_to_bytes"]