| Name | funimage JSON |
| Version |
1.0.19
JSON |
| download |
| home_page | None |
| Summary | A powerful Python library for image format conversion and processing |
| upload_time | 2025-09-11 06:06:51 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
image
conversion
pil
opencv
base64
processing
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# FunImage
[](https://badge.fury.io/py/funimage)
[](https://pypi.org/project/funimage/)
[](https://opensource.org/licenses/MIT)
一个强大的 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
```bash
pip install funimage
```
### 可选依赖 Optional Dependencies
安装 OpenCV 支持 For OpenCV support:
```bash
pip install funimage[opencv]
```
开发环境 For development:
```bash
pip install funimage[dev]
```
## 快速开始 Quick Start
```python
import funimage
# Convert URL to PIL Image
pil_img = funimage.convert_to_pilimg("https://example.com/image.jpg")
# 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("https://example.com/image.jpg", "output.jpg")
```
## 支持的输入类型 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.
```python
# 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.
```python
# 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.
```python
# 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.
```python
# 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.
```python
# 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.
```python
from funimage import ImageType, parse_image_type
img_type = parse_image_type("https://example.com/image.jpg")
print(img_type) # ImageType.URL
```
### 图像类型 Image Types
```python
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
```python
from funimage import ImageType
# Explicitly specify input type
pil_img = funimage.convert_to_pilimg(
image_data,
image_type=ImageType.BYTES
)
```
### 错误处理 Error Handling
```python
try:
pil_img = funimage.convert_to_pilimg("https://invalid-url.com/image.jpg")
except Exception as e:
print(f"Conversion failed: {e}")
```
### 批量处理 Batch Processing
```python
urls = [
"https://example.com/image1.jpg",
"https://example.com/image2.jpg",
"https://example.com/image3.jpg"
]
for i, url in enumerate(urls):
funimage.convert_to_file(url, f"image_{i}.jpg")
```
## 示例 Examples
### 网页图像抓取 Web Scraping Images
```python
import requests
from bs4 import BeautifulSoup
import funimage
# Scrape images from a webpage
response = requests.get("https://example.com")
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")
print(f"Saved image {i}")
except Exception as e:
print(f"Failed to save image {i}: {e}")
```
### 图像格式转换 Image Format Conversion
```python
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
```python
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)
return response.json()
```
## 依赖要求 Requirements
- Python >= 3.8
- PIL/Pillow >= 9.0.0
- NumPy >= 1.20.0
- Requests >= 2.25.0
## 贡献 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
## 许可证 License
本项目基于 MIT 许可证 - 详情请查看 [LICENSE](LICENSE) 文件。This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 更新日志 Changelog
### v1.0.13
- 添加完整的类型提示 Added comprehensive type hints
- 改进错误处理和日志记录 Improved error handling and logging
## 支持 Support
如果您遇到任何问题或有疑问，请在 GitHub 上 [提交 issue](https://github.com/farfarfun/funimage/issues)。If you encounter any issues or have questions, please [open an issue](https://github.com/farfarfun/funimage/issues) on GitHub.
Raw data
{
"_id": null,
"home_page": null,
"name": "funimage",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "\u725b\u54e5 <niuliangtao@qq.com>, farfarfun <farfarfun@qq.com>",
"keywords": "image, conversion, PIL, opencv, base64, processing",
"author": null,
"author_email": "\u725b\u54e5 <niuliangtao@qq.com>, farfarfun <farfarfun@qq.com>",
"download_url": null,
"platform": null,
"description": "# FunImage\n\n[](https://badge.fury.io/py/funimage)\n[](https://pypi.org/project/funimage/)\n[](https://opensource.org/licenses/MIT)\n\n\n\u4e00\u4e2a\u5f3a\u5927\u7684 Python \u56fe\u50cf\u683c\u5f0f\u8f6c\u6362\u548c\u5904\u7406\u5e93\u3002FunImage \u63d0\u4f9b\u4e86 PIL \u56fe\u50cf\u3001OpenCV \u6570\u7ec4\u3001\u5b57\u8282\u3001base64\u3001URL \u548c\u6587\u4ef6\u8def\u5f84\u4e4b\u95f4\u7684\u65e0\u7f1d\u8f6c\u6362\u529f\u80fd\u3002\n\nA 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.\n\n## \u7279\u6027 Features\n\n- \ud83d\udd04 **\u901a\u7528\u56fe\u50cf\u8f6c\u6362 Universal Image Conversion**: \u652f\u6301 PIL\u3001OpenCV\u3001\u5b57\u8282\u3001base64\u3001URL \u548c\u6587\u4ef6\u4e4b\u95f4\u7684\u8f6c\u6362 Convert between PIL, OpenCV, bytes, base64, URLs, and files\n- \ud83c\udf10 **URL \u652f\u6301 URL Support**: \u76f4\u63a5\u4ece HTTP/HTTPS URL \u52a0\u8f7d\u56fe\u50cf Direct image loading from HTTP/HTTPS URLs\n- \ud83c\udfaf **\u7c7b\u578b\u68c0\u6d4b Type Detection**: \u81ea\u52a8\u56fe\u50cf\u7c7b\u578b\u68c0\u6d4b Automatic image type detection\n- \ud83d\udce6 **\u591a\u683c\u5f0f\u652f\u6301 Multiple Formats**: \u652f\u6301 JPEG\u3001PNG\u3001WEBP\u3001AVIF \u7b49\u683c\u5f0f Support for JPEG, PNG, WEBP, AVIF, and more\n- \ud83d\udee1\ufe0f **\u9519\u8bef\u5904\u7406 Error Handling**: \u5065\u58ee\u7684\u9519\u8bef\u5904\u7406\u548c\u56de\u9000\u673a\u5236 Robust error handling with fallback mechanisms\n- \ud83d\ude80 **\u9ad8\u6027\u80fd Performance**: \u9488\u5bf9\u901f\u5ea6\u548c\u5185\u5b58\u6548\u7387\u4f18\u5316 Optimized for speed and memory efficiency\n- \ud83d\udd27 **\u7c7b\u578b\u63d0\u793a Type Hints**: \u5b8c\u6574\u7684\u7c7b\u578b\u6ce8\u89e3\u652f\u6301 Full type annotation support\n- \ud83d\udcdd **\u5b8c\u6574\u6587\u6863 Documentation**: \u8be6\u7ec6\u7684 API \u6587\u6863\u548c\u793a\u4f8b Comprehensive API documentation and examples\n\n## \u5b89\u88c5 Installation\n\n```bash\npip install funimage\n```\n\n### \u53ef\u9009\u4f9d\u8d56 Optional Dependencies\n\n\u5b89\u88c5 OpenCV \u652f\u6301 For OpenCV support:\n```bash\npip install funimage[opencv]\n```\n\n\u5f00\u53d1\u73af\u5883 For development:\n```bash\npip install funimage[dev]\n```\n\n## \u5feb\u901f\u5f00\u59cb Quick Start\n\n```python\nimport funimage\n\n# Convert URL to PIL Image\npil_img = funimage.convert_to_pilimg(\"https://example.com/image.jpg\")\n\n# Convert PIL Image to bytes\nimg_bytes = funimage.convert_to_bytes(pil_img)\n\n# Convert to base64 string\nbase64_str = funimage.convert_to_base64_str(img_bytes)\n\n# Save to file\nfunimage.convert_to_file(\"https://example.com/image.jpg\", \"output.jpg\")\n```\n\n## \u652f\u6301\u7684\u8f93\u5165\u7c7b\u578b Supported Input Types\n\n| Type | Description | Example |\n|------|-------------|---------|\n| **URL** | HTTP/HTTPS image URLs | `\"https://example.com/image.jpg\"` |\n| **File Path** | Local file paths | `\"/path/to/image.jpg\"` |\n| **PIL Image** | PIL Image objects | `PIL.Image.open(\"image.jpg\")` |\n| **Bytes** | Raw image bytes | `open(\"image.jpg\", \"rb\").read()` |\n| **Base64** | Base64 encoded strings | `\"data:image/jpeg;base64,...\"` |\n| **NumPy Array** | OpenCV/NumPy arrays | `cv2.imread(\"image.jpg\")` |\n| **BytesIO** | BytesIO objects | `BytesIO(image_bytes)` |\n\n## API \u53c2\u8003 API Reference\n\n### \u6838\u5fc3\u8f6c\u6362\u51fd\u6570 Core Conversion Functions\n\n#### `convert_to_pilimg(image, image_type=None)`\nConvert any supported image format to PIL Image.\n\n```python\n# From URL\npil_img = funimage.convert_to_pilimg(\"https://example.com/image.jpg\")\n\n# From file\npil_img = funimage.convert_to_pilimg(\"/path/to/image.jpg\")\n\n# From bytes\npil_img = funimage.convert_to_pilimg(image_bytes)\n```\n\n#### `convert_to_bytes(image, image_type=None)`\nConvert any supported image format to bytes.\n\n```python\n# From PIL Image\nimg_bytes = funimage.convert_to_bytes(pil_image)\n\n# From URL\nimg_bytes = funimage.convert_to_bytes(\"https://example.com/image.jpg\")\n```\n\n#### `convert_to_cvimg(image, image_type=None)`\nConvert any supported image format to OpenCV numpy array.\n\n```python\n# From PIL Image\ncv_img = funimage.convert_to_cvimg(pil_image)\n\n# From URL\ncv_img = funimage.convert_to_cvimg(\"https://example.com/image.jpg\")\n```\n\n#### `convert_to_base64_str(image, image_type=None)`\nConvert any supported image format to base64 string.\n\n```python\n# From PIL Image\nb64_str = funimage.convert_to_base64_str(pil_image)\n\n# From file\nb64_str = funimage.convert_to_base64_str(\"/path/to/image.jpg\")\n```\n\n#### `convert_to_file(image, output_path, image_type=None)`\nSave any supported image format to file.\n\n```python\n# From URL to file\nfunimage.convert_to_file(\"https://example.com/image.jpg\", \"local_copy.jpg\")\n\n# From PIL Image to file\nfunimage.convert_to_file(pil_image, \"output.png\")\n```\n\n### \u5de5\u5177\u51fd\u6570 Utility Functions\n\n#### `parse_image_type(image, image_type=None)`\nDetect the type of input image.\n\n```python\nfrom funimage import ImageType, parse_image_type\n\nimg_type = parse_image_type(\"https://example.com/image.jpg\")\nprint(img_type) # ImageType.URL\n```\n\n### \u56fe\u50cf\u7c7b\u578b Image Types\n\n```python\nfrom funimage import ImageType\n\nImageType.URL # HTTP/HTTPS URLs\nImageType.FILE # Local file paths \nImageType.PIL # PIL Image objects\nImageType.BYTES # Raw bytes\nImageType.BASE64_STR # Base64 strings\nImageType.NDARRAY # NumPy arrays\nImageType.BYTESIO # BytesIO objects\n```\n\n## \u9ad8\u7ea7\u7528\u6cd5 Advanced Usage\n\n### \u663e\u5f0f\u7c7b\u578b\u6307\u5b9a Explicit Type Specification\n\n```python\nfrom funimage import ImageType\n\n# Explicitly specify input type\npil_img = funimage.convert_to_pilimg(\n image_data, \n image_type=ImageType.BYTES\n)\n```\n\n### \u9519\u8bef\u5904\u7406 Error Handling\n\n```python\ntry:\n pil_img = funimage.convert_to_pilimg(\"https://invalid-url.com/image.jpg\")\nexcept Exception as e:\n print(f\"Conversion failed: {e}\")\n```\n\n### \u6279\u91cf\u5904\u7406 Batch Processing\n\n```python\nurls = [\n \"https://example.com/image1.jpg\",\n \"https://example.com/image2.jpg\", \n \"https://example.com/image3.jpg\"\n]\n\nfor i, url in enumerate(urls):\n funimage.convert_to_file(url, f\"image_{i}.jpg\")\n```\n\n## \u793a\u4f8b Examples\n\n### \u7f51\u9875\u56fe\u50cf\u6293\u53d6 Web Scraping Images\n\n```python\nimport requests\nfrom bs4 import BeautifulSoup\nimport funimage\n\n# Scrape images from a webpage\nresponse = requests.get(\"https://example.com\")\nsoup = BeautifulSoup(response.content, 'html.parser')\n\nfor i, img in enumerate(soup.find_all('img')):\n img_url = img.get('src')\n if img_url:\n try:\n funimage.convert_to_file(img_url, f\"scraped_image_{i}.jpg\")\n print(f\"Saved image {i}\")\n except Exception as e:\n print(f\"Failed to save image {i}: {e}\")\n```\n\n### \u56fe\u50cf\u683c\u5f0f\u8f6c\u6362 Image Format Conversion\n\n```python\nimport funimage\n\n# Convert PNG to JPEG\npng_image = funimage.convert_to_pilimg(\"input.png\")\nfunimage.convert_to_file(png_image, \"output.jpg\")\n\n# Convert to WebP\nfunimage.convert_to_file(\"input.jpg\", \"output.webp\")\n```\n\n### API \u96c6\u6210 API Integration\n\n```python\nimport funimage\nimport requests\n\ndef upload_image_to_api(image_path):\n # Convert image to base64 for API\n b64_str = funimage.convert_to_base64_str(image_path)\n \n payload = {\n \"image\": b64_str,\n \"format\": \"jpeg\"\n }\n \n response = requests.post(\"https://api.example.com/upload\", json=payload)\n return response.json()\n```\n\n## \u4f9d\u8d56\u8981\u6c42 Requirements\n\n- Python >= 3.8\n- PIL/Pillow >= 9.0.0\n- NumPy >= 1.20.0\n- Requests >= 2.25.0\n\n## \u8d21\u732e Contributing\n\n\u6b22\u8fce\u8d21\u732e\uff01\u8bf7\u968f\u65f6\u63d0\u4ea4 Pull Request\u3002Contributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## \u8bb8\u53ef\u8bc1 License\n\n\u672c\u9879\u76ee\u57fa\u4e8e MIT \u8bb8\u53ef\u8bc1 - \u8be6\u60c5\u8bf7\u67e5\u770b [LICENSE](LICENSE) \u6587\u4ef6\u3002This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \u66f4\u65b0\u65e5\u5fd7 Changelog\n\n### v1.0.13\n- \u6dfb\u52a0\u5b8c\u6574\u7684\u7c7b\u578b\u63d0\u793a Added comprehensive type hints\n- \u6539\u8fdb\u9519\u8bef\u5904\u7406\u548c\u65e5\u5fd7\u8bb0\u5f55 Improved error handling and logging\n\n## \u652f\u6301 Support\n\n\u5982\u679c\u60a8\u9047\u5230\u4efb\u4f55\u95ee\u9898\u6216\u6709\u7591\u95ee\uff0c\u8bf7\u5728 GitHub \u4e0a [\u63d0\u4ea4 issue](https://github.com/farfarfun/funimage/issues)\u3002If you encounter any issues or have questions, please [open an issue](https://github.com/farfarfun/funimage/issues) on GitHub.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A powerful Python library for image format conversion and processing",
"version": "1.0.19",
"project_urls": {
"Organization": "https://github.com/farfarfun",
"Releases": "https://github.com/farfarfun/funimage/releases",
"Repository": "https://github.com/farfarfun/funimage"
},
"split_keywords": [
"image",
" conversion",
" pil",
" opencv",
" base64",
" processing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d6fc468f043ce07c44218920d6116a91f198eafe791cd6b35e5a58d3c3b6d242",
"md5": "924c0bf66f211032d30bed4ca866d4c8",
"sha256": "70be6f84f4470cce607cccb01bf08c0d0dcb4dabebe7cd443d2e6d3c4ab1c3a4"
},
"downloads": -1,
"filename": "funimage-1.0.19-py3-none-any.whl",
"has_sig": false,
"md5_digest": "924c0bf66f211032d30bed4ca866d4c8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8163,
"upload_time": "2025-09-11T06:06:51",
"upload_time_iso_8601": "2025-09-11T06:06:51.382796Z",
"url": "https://files.pythonhosted.org/packages/d6/fc/468f043ce07c44218920d6116a91f198eafe791cd6b35e5a58d3c3b6d242/funimage-1.0.19-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 06:06:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "farfarfun",
"github_project": "funimage",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "funimage"
}
