FunImage

一个强大的 Python 图像格式转换和处理库。FunImage 提供了 PIL 图像、OpenCV 数组、字节、base64、URL 和文件路径之间的无缝转换功能。

A powerful Python library for image format conversion and processing. FunImage provides seamless conversion between various image formats including PIL Images, OpenCV arrays, bytes, base64, URLs, and file paths.

特性 Features

• 🔄 通用图像转换 Universal Image Conversion: 支持 PIL、OpenCV、字节、base64、URL 和文件之间的转换 Convert between PIL, OpenCV, bytes, base64, URLs, and files
• 🌐 URL 支持 URL Support: 直接从 HTTP/HTTPS URL 加载图像 Direct image loading from HTTP/HTTPS URLs
• 🎯 类型检测 Type Detection: 自动图像类型检测 Automatic image type detection
• 📦 多格式支持 Multiple Formats: 支持 JPEG、PNG、WEBP、AVIF 等格式 Support for JPEG, PNG, WEBP, AVIF, and more
• 🛡️ 错误处理 Error Handling: 健壮的错误处理和回退机制 Robust error handling with fallback mechanisms
• 🚀 高性能 Performance: 针对速度和内存效率优化 Optimized for speed and memory efficiency
• 🔧 类型提示 Type Hints: 完整的类型注解支持 Full type annotation support
• 📝 完整文档 Documentation: 详细的 API 文档和示例 Comprehensive API documentation and examples

安装 Installation

pip install funimage

可选依赖 Optional Dependencies

安装 OpenCV 支持 For OpenCV support:

pip install funimage[opencv]

快速开始 Quick Start

下面示例只依赖 PIL 在本地生成的图像，无需网络即可直接运行 The example below only uses a PIL-generated local image and runs without any network access:

import PIL.Image

import funimage

# 本地生成一张测试图片，无需网络 Generate a local test image, no network required
pil_img = PIL.Image.new("RGB", (64, 64), color="red")

# Convert PIL Image to bytes
img_bytes = funimage.convert_to_bytes(pil_img)

# Convert to base64 string
base64_str = funimage.convert_to_base64_str(img_bytes)

# Save to file
funimage.convert_to_file(pil_img, "output.jpg")

从 HTTP/HTTPS URL 加载图像需要目标地址真实可达；地址不可达时 convert_to_pilimg、 convert_to_file 等函数会抛出 ValueError，调用方应按具体异常类型捕获处理 （见下方「错误处理」）。Loading from an HTTP/HTTPS URL requires the target address to be reachable; on failure, functions like convert_to_pilimg and convert_to_file raise ValueError, which callers should catch by specific exception type (see "Error Handling" below).

支持的输入类型 Supported Input Types

Type	Description	Example
URL	HTTP/HTTPS image URLs	"https://example.com/image.jpg"
File Path	Local file paths	"/path/to/image.jpg"
PIL Image	PIL Image objects	PIL.Image.open("image.jpg")
Bytes	Raw image bytes	open("image.jpg", "rb").read()
Base64	Base64 encoded strings	"data:image/jpeg;base64,..."
NumPy Array	OpenCV/NumPy arrays	cv2.imread("image.jpg")
BytesIO	BytesIO objects	BytesIO(image_bytes)

API 参考 API Reference

核心转换函数 Core Conversion Functions

convert_to_pilimg(image, image_type=None)

Convert any supported image format to PIL Image.

# From URL
pil_img = funimage.convert_to_pilimg("https://example.com/image.jpg")

# From file
pil_img = funimage.convert_to_pilimg("/path/to/image.jpg")

# From bytes
pil_img = funimage.convert_to_pilimg(image_bytes)

convert_to_bytes(image, image_type=None)

Convert any supported image format to bytes.

# From PIL Image
img_bytes = funimage.convert_to_bytes(pil_image)

# From URL
img_bytes = funimage.convert_to_bytes("https://example.com/image.jpg")

convert_to_cvimg(image, image_type=None)

Convert any supported image format to OpenCV numpy array.

# From PIL Image
cv_img = funimage.convert_to_cvimg(pil_image)

# From URL
cv_img = funimage.convert_to_cvimg("https://example.com/image.jpg")

convert_to_base64_str(image, image_type=None)

Convert any supported image format to base64 string.

# From PIL Image
b64_str = funimage.convert_to_base64_str(pil_image)

# From file
b64_str = funimage.convert_to_base64_str("/path/to/image.jpg")

convert_to_file(image, output_path, image_type=None)

Save any supported image format to file.

# From URL to file
funimage.convert_to_file("https://example.com/image.jpg", "local_copy.jpg")

# From PIL Image to file
funimage.convert_to_file(pil_image, "output.png")

工具函数 Utility Functions

parse_image_type(image, image_type=None)

Detect the type of input image.

from funimage import ImageType, parse_image_type

img_type = parse_image_type("https://example.com/image.jpg")
print(img_type)  # ImageType.URL

图像类型 Image Types

from funimage import ImageType

ImageType.URL          # HTTP/HTTPS URLs
ImageType.FILE         # Local file paths  
ImageType.PIL          # PIL Image objects
ImageType.BYTES        # Raw bytes
ImageType.BASE64_STR   # Base64 strings
ImageType.NDARRAY      # NumPy arrays
ImageType.BYTESIO      # BytesIO objects

高级用法 Advanced Usage

显式类型指定 Explicit Type Specification

from funimage import ImageType

# Explicitly specify input type
pil_img = funimage.convert_to_pilimg(
    image_data, 
    image_type=ImageType.BYTES
)

错误处理 Error Handling

funimage 的转换函数在输入不受支持或 URL 下载失败时抛出 ValueError，应按具体异常类型 捕获并以非零退出码结束，而不是用 except Exception 吞掉错误。

funimage's conversion functions raise ValueError when the input is unsupported or a URL download fails; catch that specific exception type and exit with a non-zero status instead of swallowing errors with except Exception:

import sys

try:
    pil_img = funimage.convert_to_pilimg("https://invalid-url.example/image.jpg")
except ValueError as exc:
    sys.exit(f"图像转换失败：{exc}")

批量处理 Batch Processing

import PIL.Image

images = [
    PIL.Image.new("RGB", (32, 32), color="red"),
    PIL.Image.new("RGB", (32, 32), color="green"),
    PIL.Image.new("RGB", (32, 32), color="blue"),
]

for i, image in enumerate(images):
    funimage.convert_to_file(image, f"image_{i}.jpg")

示例 Examples

网页图像抓取 Web Scraping Images

该示例依赖目标网页可访问，运行前请确认网络环境 This example requires the target page to be reachable; make sure network access is available before running it:

from farlog import getLogger
import requests
from bs4 import BeautifulSoup
import funimage

logger = getLogger("funimage-example")

# Scrape images from a webpage
response = requests.get("https://example.com", timeout=10)
soup = BeautifulSoup(response.content, 'html.parser')

for i, img in enumerate(soup.find_all('img')):
    img_url = img.get('src')
    if img_url:
        try:
            funimage.convert_to_file(img_url, f"scraped_image_{i}.jpg")
        except ValueError as exc:
            logger.error("第 {} 张图片保存失败：{}", i, exc)

图像格式转换 Image Format Conversion

import funimage

# Convert PNG to JPEG
png_image = funimage.convert_to_pilimg("input.png")
funimage.convert_to_file(png_image, "output.jpg")

# Convert to WebP
funimage.convert_to_file("input.jpg", "output.webp")

API 集成 API Integration

import funimage
import requests

def upload_image_to_api(image_path):
    # Convert image to base64 for API
    b64_str = funimage.convert_to_base64_str(image_path)
    
    payload = {
        "image": b64_str,
        "format": "jpeg"
    }
    
    response = requests.post("https://api.example.com/upload", json=payload, timeout=10)
    return response.json()

依赖要求 Requirements

• Python >= 3.12
• PIL/Pillow >= 9.0.0
• NumPy >= 1.20.0
• FunGet >= 1.1.63

贡献 Contributing

欢迎贡献！请随时提交 Pull Request。Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

支持 Support

如果您遇到任何问题或有疑问，请在 GitHub 上 提交 issue。If you encounter any issues or have questions, please open an issue on GitHub.

---

关于 farfarfun

farfarfun 是一个专注于实用工具库的开源组织， 涵盖云存储、数据处理、AI、多媒体与开发工具链等方向。

• 🏠 组织主页：https://github.com/farfarfun
• 📦 PyPI：https://pypi.org/user/niuliangtao/
• 📧 联系：farfarfun@qq.com

本项目基于 MIT 协议开源。