[python]通过whl文件安装pyheif安装教程和简单使用案例

pyheif如果直接pip install pyheif是安装不上的需要借助whl文件可以很轻松安装成功。下面我们开始进行讲述如何安装。首先我们必须搞清楚whl文件名含义：这里以pyheif-0.6.1-cp39-cp39-win_amd64.whl 为例，通过了解whl文件名结构我们可以找到对应自己python版本和操作系统。

pyheif-0.6.1-cp39-cp39-win_amd64.whl 是一个 Python 的 Wheel 文件（.whl 格式），它是用于分发 Python 包的预编译二进制文件。以下是对该文件名各个部分的解析：

1. 文件名整体结构

|---|----------------------------------------|
| | pyheif-0.6.1-cp39-cp39-win_amd64.whl |

pyheif ：

这是包的名称，表示该文件对应的是 pyheif 这个 Python 包。pyheif 是一个用于处理 HEIF（High Efficiency Image File Format，高效图像文件格式）的 Python 库。
0.6.1 ：

这是包的版本号，表示该文件是 pyheif 包的第 0.6.1 版本。
cp39-cp39 ：

这是与 Python 版本相关的信息：
- cp39 表示该包是为 CPython 3.9 编译的。只适合python3.9使用
- 第二个 cp39 再次强调了它兼容的 Python 实现和版本。
win_amd64 ：

这是与操作系统和硬件架构相关的信息：
- win 表示该包是为 Windows 操作系统构建的。
- amd64 表示该包是为 64 位的 x86_64（AMD64）架构 构建的。
.whl ：

这是文件的扩展名，表示该文件是一个 Python 的 Wheel 包。

2. 这个文件的作用

该文件是一个预编译的二进制包，包含了 pyheif 的代码和所需的依赖，用户可以直接安装它，而无需从源码编译。
如果你使用的是 Windows 64 位操作系统 和 Python 3.9 ，可以直接使用 pip 安装这个包。

3. 如何安装这个文件

如果你已经下载了该 .whl 文件，可以通过以下命令安装：

|---|----------------------------------------------------|
| | pip install pyheif-0.6.1-cp39-cp39-win_amd64.whl |

如果你在 Windows 系统中，并且 pip 已正确配置，这条命令会自动安装该包。

4. 适用环境

Python 版本：Python 3.9
操作系统：Windows
架构：64 位（x86_64 / AMD64）

如果你的环境不匹配（例如，你使用的是 Python 3.10 或 32 位系统），则需要下载与你的环境兼容的 .whl 文件，或者从源码安装。

5. 关于 `pyheif`

pyheif 是一个 Python 库，用于读取和写入 HEIF 格式的图像文件。
HEIF 是一种高效的图像文件格式，常用于存储高质量图片（如 HEIC 格式）。
如果你需要处理 HEIF 格式的图片，这个包会非常有用。

【安装步骤】

以下是使用 .whl 文件安装 pyheif 的详细教程，适用于 Windows 系统：

一、安装前的准备

安装 Python 和 pip
- 确保已安装 Python（建议使用 3.7 及以上版本）。
- 安装时勾选 "Add Python to PATH" 选项，或手动将 Python 和 Scripts 目录添加到系统环境变量。
- 验证安装：打开命令提示符，输入以下命令：
  
  |---|--------------------|
  | | python --version |
  | | pip --version |
  
  确保显示正确的版本号。
下载 pyheif 的 .whl 文件
- 由于 PyPI 官方源未提供 Windows 版本的 pyheif，需从第三方源下载：
  - 推荐镜像：gitee.com/FIRC/pythonlibs_whl_mirror
  - 搜索并下载与 Python 版本和系统架构匹配的 .whl 文件，例如：
    - Python 3.9 64 位：pyheif-0.8.0-cp39-cp39-win_amd64.whl
    - Python 3.10 64 位：pyheif-0.8.0-cp310-cp310-win_amd64.whl

目前我找到了下面所有版本列表：

pyheif-0.8.0-cp313-cp313-win_amd64.whl

pyheif-0.8.0-cp312-cp312-win_amd64.whl

pyheif-0.8.0-cp311-cp311-win_amd64.whl

pyheif-0.8.0-cp310-cp310-win_amd64.whl

pyheif-0.8.0-cp39-cp39-win_amd64.whl

pyheif-0.8.0-cp38-cp38-win_amd64.whl

pyheif-0.8.0-cp37-cp37m-win_amd64.whl

pyheif-0.7.0-cp313-cp313-win_amd64.whl

pyheif-0.7.0-cp312-cp312-win_amd64.whl

pyheif-0.7.0-cp311-cp311-win_amd64.whl

pyheif-0.7.0-cp310-cp310-win_amd64.whl

pyheif-0.7.0-cp39-cp39-win_amd64.whl

pyheif-0.7.0-cp38-cp38-win_amd64.whl

pyheif-0.7.0-cp37-cp37m-win_amd64.whl

pyheif-0.6.1-cp313-cp313-win_amd64.whl

pyheif-0.6.1-cp312-cp312-win_amd64.whl

pyheif-0.6.1-cp311-cp311-win_amd64.whl

pyheif-0.6.1-cp310-cp310-win_amd64.whl

pyheif-0.6.1-cp39-cp39-win_amd64.whl

pyheif-0.6.1-cp38-cp38-win_amd64.whl

pyheif-0.6.1-cp37-cp37m-win_amd64.whl

pyheif-0.5.1-cp313-cp313-win_amd64.whl

pyheif-0.5.1-cp312-cp312-win_amd64.whl

pyheif-0.5.1-cp311-cp311-win_amd64.whl

pyheif-0.5.1-cp310-cp310-win_amd64.whl

pyheif-0.5.1-cp39-cp39-win_amd64.whl

pyheif-0.5.1-cp38-cp38-win_amd64.whl

pyheif-0.5.1-cp37-cp37m-win_amd64.whl

二、安装 `.whl` 文件

打开命令提示符
- 按 Win + R，输入 cmd，按回车。
导航到 .whl 文件所在目录
- 使用 cd 命令切换到文件路径，例如：
  
  |---|-------------------|
  | | cd C:\Downloads |
安装 .whl 文件
- 运行以下命令（将 文件名 替换为实际下载的文件名）：
  
  |---|-----------------------|
  | | pip install 文件名.whl |
- 示例：
  
  |---|----------------------------------------------------|
  | | pip install pyheif-0.8.0-cp39-cp39-win_amd64.whl |
验证安装
- 输入以下命令检查版本：
  
  |---|--------------------------------------------------------|
  | | python -c "import pyheif; print(pyheif.__version__)" |
- 如果显示版本号（如 0.8.0），则安装成功。

三、测试安装

读取 HEIC 文件
- 示例代码：
from pyheif import read

image = read('images/arrow.heic')

将HEIC图像转换为PIL图像以便显示或进一步处理

from PIL import Image
pil_image = Image.frombytes(
mode=image.mode,
size=image.size,
data=image.data,
decoder_name='raw'
)
pil_image.show()
运行代码
- 将代码保存为 test.py，运行：
  
  |---|------------------|
  | | python test.py |
- 如果成功显示图像，则 pyheif 工作正常。

温馨提示：代码已经在0.5.1,0.6.1,0.7.0,0.8.0版本均测试通过，完整源码：firc.lanzn.com/i3ENU2h7upjg

四、常见问题及解决方法

pip 不是内部或外部命令
- 确保 Python 和 Scripts 目录已添加到系统环境变量。
版本不兼容
- 确保下载的 .whl 文件与 Python 版本和系统架构匹配。
- 检查 Python 版本：
  
  |---|--------------------|
  | | python --version |
- 检查系统架构（32 位或 64 位）：
  - 右键 "此电脑" -> "属性" -> 查看系统类型。
缺少依赖项
- 某些第三方源的 .whl 文件已包含依赖项（如 libheif 和 libde265），无需额外安装。
- 如果从源码编译，需手动安装依赖项。

按照以上步骤，你应该能够成功安装并使用 pyheif。如果遇到问题，请检查错误信息并根据提示调整安装步骤。