picx-image-optimizer 0.1.0__tar.gz

picx_image_optimizer-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Tests
+        run: python -m pytest
+      - name: Compile
+        run: python -m compileall -q src tests examples
+      - name: Ruff
+        run: python -m ruff check .
+      - name: Black
+        run: python -m black --check .
+      - name: Mypy
+        run: python -m mypy src tests examples

picx_image_optimizer-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install build tooling
+        run: python -m pip install build twine
+
+      - name: Build source and wheel distributions
+        run: python -m build
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/picx-image-optimizer/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

picx_image_optimizer-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.py[cod]
+.venv/
+.DS_Store
+dist/

picx_image_optimizer-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Added CLI and Python APIs for image optimization.
+- Added Pillow and pyvips backends.
+- Added large-image guidance, TIFF support, WebP dimension checks, and tile output with manifests.
+- Added English and Chinese README files.

picx_image_optimizer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ingeniousfrog
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

picx_image_optimizer-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: picx-image-optimizer
+Version: 0.1.0
+Summary: A tiny Python image optimization toolkit for batch compression and web assets.
+Project-URL: Homepage, https://github.com/ingeniousfrog/picx
+Project-URL: Issues, https://github.com/ingeniousfrog/picx/issues
+Project-URL: Repository, https://github.com/ingeniousfrog/picx
+Author: ingeniousfrog
+License: MIT
+License-File: LICENSE
+Keywords: compression,image,optimization,tiff,tiles,webp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.9
+Requires-Dist: pillow>=10.0
+Requires-Dist: pyvips>=2.2
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: mypy<2,>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# picx
+
+picx is a small Python image optimization package for web assets, blogs, avatars,
+and batch cleanup jobs. The package installs a CLI named `picx` and exposes a
+compact Python API under `picx`.
+
+## Features
+
+- Compress single images or entire directories.
+- Convert between `jpg`, `png`, `webp`, `avif`, and `tiff` outputs.
+- Read `jpg`, `jpeg`, `png`, `webp`, `avif`, `tif`, and `tiff` inputs.
+- Resize with `max_width` and `max_height`.
+- Strip image metadata by default.
+- Search for the highest quality under a target byte size.
+- Render CLI compression reports with Rich.
+- Use `web`, `blog`, `avatar`, and `lossless` presets.
+
+## Install
+
+```bash
+pip install -e ".[dev]"
+```
+
+`pip install picx-image-optimizer` installs the pyvips Python backend package. pyvips also
+needs the native libvips system library for large-image processing. pip cannot
+install this native system library for every platform, so install it once with
+your OS or environment package manager:
+
+```bash
+brew install vips
+# or
+conda install -c conda-forge libvips pyvips
+```
+
+Install libvips in the same environment that runs `picx`. For example, if you
+run `picx` inside `conda activate comfyui`, install libvips inside that conda
+environment. Mixing Homebrew libvips with Anaconda/conda libraries can still
+fail on macOS with dynamic-library or code-signature errors.
+
+## CLI
+
+Optimize one image:
+
+```bash
+picx image ./photo.png --output ./dist/photo.webp --format webp --quality 82
+```
+
+Optimize a directory recursively while preserving relative paths:
+
+```bash
+picx dir ./images ./out --format webp --preset web
+```
+
+Try a target size in bytes:
+
+```bash
+picx image ./hero.jpg --output ./out/hero.webp --format webp --target-size 120000
+```
+
+Handle trusted large images with Pillow:
+
+```bash
+picx image ./texture.tif --output ./texture.webp --format webp --allow-large --max-pixels 400000000
+```
+
+Use the pyvips backend for large images:
+
+```bash
+picx image ./texture.tif --output ./texture.webp --format webp --backend pyvips
+```
+
+WebP has a per-side dimension limit of 16383 pixels. If either width or height
+is larger, resize first or use tiling:
+
+```bash
+picx image ./texture.tif --output ./texture.webp --format webp --backend pyvips --max-height 16000
+```
+
+Create tiles and a manifest for very large images:
+
+```bash
+picx tile ./texture.tif ./tiles --tile-size 1024 --format webp
+```
+
+## Python API
+
+```python
+from picx import optimize_dir, optimize_image, tile_image
+
+single = optimize_image(
+    "photo.png",
+    output="dist/photo.webp",
+    format="webp",
+    quality=82,
+    max_width=1600,
+    strip_meta=True,
+)
+
+batch = optimize_dir(
+    "images",
+    "out",
+    format="webp",
+    preset="blog",
+    recursive=True,
+)
+
+tiles = tile_image("texture.tif", "tiles", tile_size=1024, format="webp")
+```
+
+`optimize_image()` and `optimize_dir()` return `OptimizeResult` objects with:
+
+- `original_size`
+- `output_size`
+- `savings_ratio`
+- `skipped`
+- `error`
+- `source_path`
+- `output_path`
+
+## Presets
+
+| Preset | Output | Purpose |
+| --- | --- | --- |
+| `web` | webp, quality 82, max width 1920 | General website images |
+| `blog` | webp, quality 78, max width 1600 | Blog and article images |
+| `avatar` | webp, quality 85, max 256 x 256 | Profile images |
+| `lossless` | png, quality 100 | Lossless-ish cleanup with metadata stripping |
+
+## Development
+
+```bash
+python3 -m pytest
+```
+
+picx uses Pillow by default and includes the pyvips Python backend package.
+The pyvips backend also requires the native libvips system library, which pip
+does not install automatically. Install libvips in the same environment that
+runs `picx`.
+
+## Large Images
+
+By default, picx keeps Pillow's large-image safety posture. If an image exceeds
+the configured pixel limit, picx reports a clear error with next steps instead
+of showing a raw traceback. For trusted images, use `--allow-large` and optionally
+set `--max-pixels`. For memory-efficient processing, install system libvips and
+select `--backend pyvips` or keep the default `--backend auto`.
+
+For single-file WebP output, keep both width and height at or below 16383 pixels.
+Images larger than that should be resized with `--max-width` / `--max-height`, or
+exported with `picx tile` instead.
+
+`picx tile` writes image tiles plus `manifest.json`. The manifest is an index,
+not a merged image: it records the original size, tile size, output format,
+levels, and every tile's path and coordinates so another tool can display or
+reconstruct the tile layout reliably.

picx_image_optimizer-0.1.0/README-CN.md

@@ -0,0 +1,167 @@
+# picx
+
+picx 是一个轻量的 Python 图片优化工具包，适合处理网页图片、博客配图、头像和批量压缩任务。它同时提供命令行工具 `picx` 和 Python API。
+
+## 功能
+
+- 压缩单张图片或整个目录。
+- 支持输出 `jpg`、`png`、`webp`、`avif`、`tiff`。
+- 支持读取 `jpg`、`jpeg`、`png`、`webp`、`avif`、`tif`、`tiff`。
+- 支持按 `max_width` / `max_height` 缩放。
+- 默认清理图片元数据。
+- 支持按目标体积搜索尽可能高的输出质量。
+- 使用 Rich 输出压缩报告。
+- 内置 `web`、`blog`、`avatar`、`lossless` 四个 preset。
+- 支持 pyvips 后端和切片输出，用于处理超大图。
+
+## 安装
+
+开发安装：
+
+```bash
+pip install -e ".[dev]"
+```
+
+正式使用时：
+
+```bash
+pip install picx-image-optimizer
+```
+
+`pip install picx-image-optimizer` 会安装 pyvips 的 Python 包，但 pyvips 还需要系统原生库 libvips。pip 无法在所有平台上可靠安装这个系统库，所以需要用系统或环境包管理器额外安装一次：
+
+```bash
+brew install vips
+# 或
+conda install -c conda-forge libvips pyvips
+```
+
+注意：libvips 要安装在运行 `picx` 的同一个环境里。比如你在 `conda activate comfyui` 后运行 `picx`，就要在这个 conda 环境里安装 libvips。macOS 上混用 Homebrew 的 libvips 和 Anaconda/conda 的动态库，仍然可能遇到动态库加载或代码签名错误。
+
+## CLI 用法
+
+压缩单张图片：
+
+```bash
+picx image ./photo.png --output ./dist/photo.webp --format webp --quality 82
+```
+
+递归压缩目录，并保持相对目录结构：
+
+```bash
+picx dir ./images ./out --format webp --preset web
+```
+
+按目标体积压缩：
+
+```bash
+picx image ./hero.jpg --output ./out/hero.webp --format webp --target-size 120000
+```
+
+用 Pillow 处理可信的大图：
+
+```bash
+picx image ./texture.tif --output ./texture.webp --format webp --allow-large --max-pixels 400000000
+```
+
+用 pyvips 后端处理大图：
+
+```bash
+picx image ./texture.tif --output ./texture.webp --format webp --backend pyvips
+```
+
+WebP 单边尺寸上限通常是 16383 像素。如果宽或高超过这个限制，需要先缩放，或者改用切片：
+
+```bash
+picx image ./texture.tif --output ./texture.webp --format webp --backend pyvips --max-height 16000
+```
+
+为超大图生成切片和 manifest：
+
+```bash
+picx tile ./texture.tif ./tiles --tile-size 1024 --format webp
+```
+
+## Python API
+
+```python
+from picx import optimize_dir, optimize_image, tile_image
+
+single = optimize_image(
+    "photo.png",
+    output="dist/photo.webp",
+    format="webp",
+    quality=82,
+    max_width=1600,
+    strip_meta=True,
+)
+
+batch = optimize_dir(
+    "images",
+    "out",
+    format="webp",
+    preset="blog",
+    recursive=True,
+)
+
+tiles = tile_image("texture.tif", "tiles", tile_size=1024, format="webp")
+```
+
+`optimize_image()` 和 `optimize_dir()` 返回 `OptimizeResult`，包含：
+
+- `original_size`
+- `output_size`
+- `savings_ratio`
+- `skipped`
+- `error`
+- `source_path`
+- `output_path`
+
+## Preset
+
+| Preset | 输出 | 用途 |
+| --- | --- | --- |
+| `web` | webp，quality 82，最大宽度 1920 | 通用网页图片 |
+| `blog` | webp，quality 78，最大宽度 1600 | 博客和文章配图 |
+| `avatar` | webp，quality 85，最大 256 x 256 | 头像 |
+| `lossless` | png，quality 100 | 偏无损的清理和元数据移除 |
+
+## 大图处理
+
+默认情况下，picx 会保留 Pillow 的大图安全策略。如果图片超过像素限制，picx 会给出清晰错误和下一步建议，而不是直接抛出原始 traceback。
+
+如果图片来源可信，可以使用：
+
+```bash
+--allow-large --max-pixels 400000000
+```
+
+如果希望更省内存地处理超大 TIFF、PNG 等图片，优先使用：
+
+```bash
+--backend pyvips
+```
+
+pyvips 的 Python 包会随 `picx` 安装，但原生 libvips 需要单独安装，并且必须安装在运行 `picx` 的同一个环境里。
+
+## WebP 尺寸限制
+
+单个 WebP 文件的宽和高都应不超过 16383 像素。超过这个尺寸时，即使 pyvips 能读入原图，编码成单个 WebP 也可能失败。
+
+解决方式：
+
+- 用 `--max-width` / `--max-height` 缩放到限制以内。
+- 使用 `picx tile` 输出切片。
+- 改用适合大图的其它格式。
+
+## 切片和 manifest
+
+`picx tile` 会输出一组 tile 图片和 `manifest.json`。
+
+manifest 不是合并后的大图，而是切片索引。它记录原图尺寸、tile 大小、输出格式、层级，以及每张 tile 的路径和坐标。查看器或后续工具可以根据这些坐标可靠地展示或重建切片布局。
+
+## 开发
+
+```bash
+python3 -m pytest
+```

picx_image_optimizer-0.1.0/README.md

@@ -0,0 +1,155 @@
+# picx
+
+picx is a small Python image optimization package for web assets, blogs, avatars,
+and batch cleanup jobs. The package installs a CLI named `picx` and exposes a
+compact Python API under `picx`.
+
+## Features
+
+- Compress single images or entire directories.
+- Convert between `jpg`, `png`, `webp`, `avif`, and `tiff` outputs.
+- Read `jpg`, `jpeg`, `png`, `webp`, `avif`, `tif`, and `tiff` inputs.
+- Resize with `max_width` and `max_height`.
+- Strip image metadata by default.
+- Search for the highest quality under a target byte size.
+- Render CLI compression reports with Rich.
+- Use `web`, `blog`, `avatar`, and `lossless` presets.
+
+## Install
+
+```bash
+pip install -e ".[dev]"
+```
+
+`pip install picx-image-optimizer` installs the pyvips Python backend package. pyvips also
+needs the native libvips system library for large-image processing. pip cannot
+install this native system library for every platform, so install it once with
+your OS or environment package manager:
+
+```bash
+brew install vips
+# or
+conda install -c conda-forge libvips pyvips
+```
+
+Install libvips in the same environment that runs `picx`. For example, if you
+run `picx` inside `conda activate comfyui`, install libvips inside that conda
+environment. Mixing Homebrew libvips with Anaconda/conda libraries can still
+fail on macOS with dynamic-library or code-signature errors.
+
+## CLI
+
+Optimize one image:
+
+```bash
+picx image ./photo.png --output ./dist/photo.webp --format webp --quality 82
+```
+
+Optimize a directory recursively while preserving relative paths:
+
+```bash
+picx dir ./images ./out --format webp --preset web
+```
+
+Try a target size in bytes:
+
+```bash
+picx image ./hero.jpg --output ./out/hero.webp --format webp --target-size 120000
+```
+
+Handle trusted large images with Pillow:
+
+```bash
+picx image ./texture.tif --output ./texture.webp --format webp --allow-large --max-pixels 400000000
+```
+
+Use the pyvips backend for large images:
+
+```bash
+picx image ./texture.tif --output ./texture.webp --format webp --backend pyvips
+```
+
+WebP has a per-side dimension limit of 16383 pixels. If either width or height
+is larger, resize first or use tiling:
+
+```bash
+picx image ./texture.tif --output ./texture.webp --format webp --backend pyvips --max-height 16000
+```
+
+Create tiles and a manifest for very large images:
+
+```bash
+picx tile ./texture.tif ./tiles --tile-size 1024 --format webp
+```
+
+## Python API
+
+```python
+from picx import optimize_dir, optimize_image, tile_image
+
+single = optimize_image(
+    "photo.png",
+    output="dist/photo.webp",
+    format="webp",
+    quality=82,
+    max_width=1600,
+    strip_meta=True,
+)
+
+batch = optimize_dir(
+    "images",
+    "out",
+    format="webp",
+    preset="blog",
+    recursive=True,
+)
+
+tiles = tile_image("texture.tif", "tiles", tile_size=1024, format="webp")
+```
+
+`optimize_image()` and `optimize_dir()` return `OptimizeResult` objects with:
+
+- `original_size`
+- `output_size`
+- `savings_ratio`
+- `skipped`
+- `error`
+- `source_path`
+- `output_path`
+
+## Presets
+
+| Preset | Output | Purpose |
+| --- | --- | --- |
+| `web` | webp, quality 82, max width 1920 | General website images |
+| `blog` | webp, quality 78, max width 1600 | Blog and article images |
+| `avatar` | webp, quality 85, max 256 x 256 | Profile images |
+| `lossless` | png, quality 100 | Lossless-ish cleanup with metadata stripping |
+
+## Development
+
+```bash
+python3 -m pytest
+```
+
+picx uses Pillow by default and includes the pyvips Python backend package.
+The pyvips backend also requires the native libvips system library, which pip
+does not install automatically. Install libvips in the same environment that
+runs `picx`.
+
+## Large Images
+
+By default, picx keeps Pillow's large-image safety posture. If an image exceeds
+the configured pixel limit, picx reports a clear error with next steps instead
+of showing a raw traceback. For trusted images, use `--allow-large` and optionally
+set `--max-pixels`. For memory-efficient processing, install system libvips and
+select `--backend pyvips` or keep the default `--backend auto`.
+
+For single-file WebP output, keep both width and height at or below 16383 pixels.
+Images larger than that should be resized with `--max-width` / `--max-height`, or
+exported with `picx tile` instead.
+
+`picx tile` writes image tiles plus `manifest.json`. The manifest is an index,
+not a merged image: it records the original size, tile size, output format,
+levels, and every tile's path and coordinates so another tool can display or
+reconstruct the tile layout reliably.

picx_image_optimizer-0.1.0/examples/basic_usage.py

@@ -0,0 +1,20 @@
+from picx import optimize_dir, optimize_image
+
+
+def main() -> None:
+    image_result = optimize_image(
+        "assets/photo.jpg",
+        output="out/photo.webp",
+        format="webp",
+        quality=82,
+        max_width=1600,
+        target_size=120_000,
+    )
+    print(image_result)
+
+    dir_results = optimize_dir("assets", "out", preset="web")
+    print(f"optimized {len(dir_results)} images")
+
+
+if __name__ == "__main__":
+    main()