图形工具使用指南

概述

本指南介绍图形工具包中的图片压缩打包、多语言字符串转换、离线表盘 XML 转换、视频首帧提取、Lottie 转换和多媒体处理工具，覆盖运行准备、命令参数、结果校验及问题处理。

准备

工具包位置

图形工具交付包为仓库中的 /tools/graphic_tools.tar.gz。解压后以 graphic_tools 为根目录：图片压缩打包工具位于 graphic_tools/image_converter_tool，多语言字符串转换工具位于 graphic_tools/string_packer，视频首帧工具位于 graphic_tools/convert_2_bmp。

Python 环境与模块

图片压缩、多语言字符串转换和视频处理工具使用 Python 3.8。安装界面与通用环境配置方法请参见开发环境快速入门，建议优先使用一站式 CLI 开发环境；Windows 安装包可从 Python 官方地址获取。

按所用功能准备 opencv-python、numpy、scipy、matplotlib、pillow 和 ffmpeg-python；版本与获取方式以各项目页为准。

工具目录

图片压缩打包工具位于 graphic_tools/image_converter_tool，多语言字符串转换工具位于 graphic_tools/string_packer。

FFmpeg

多媒体工具需要 FFmpeg。通用环境配置参见开发环境快速入门，安装包和平台说明参见 FFmpeg 官方下载页。

快速操作

图片压缩打包

按Python 环境与模块准备运行环境。
准备配置 XML、输入图片目录与输出目录。
在“images_tool.py”所在路径运行压缩命令；完整命令与示例参见压缩与解压实例。
按结果校验确认命令输出和生成文件。

多语言字符串转换

按Python 环境与模块准备运行环境。
在“language_trans.py”所在路径执行转换命令；完整示例参见转换实例。
在指定输出路径确认 .lang 文件和头文件。

视频首帧提取

按获取视频第一帧工具参数准备视频文件、视频帧宽高和输出路径。
执行 convert\_2\_bmp.py 示例命令，完整命令请参见转换实例。
在输出目录使用生成的 .bmp 文件作为视频浏览帧。

其他工具

离线表盘 XML 转换工具请参见离线表盘 XML 转换工具。
Lottie 文件转换请参见Lottie 工具。
视频预旋转与首帧提取请参见多媒体工具参数与使用方式。

图形/命令行

图片压缩打包工具

通过调用图片压缩打包工具将图片压缩为单板可识别的bin文件。

压缩与解压实例

压缩模式

压缩模式如下：进入到“images_tool.py”文件的保存路径下，并在该路径下运行cmd，在cmd命令行中输入命令“python images_tool.py -p file -d cmp -c config.xml -i test\hert\ -o output\ -t include\”。如图2所示。

说明： 上述命令中，“-o”后面的输入参数对应.bin文件生成的路径，“-t”后面的输入参数对应头文件生成的路径。即：

.bin文件生成路径：graphic_tools\image_converter_tool\output

头文件生成路径：graphic_tools\image_converter_tool\include

图 1 压缩的配置文件xml

**图 1** 压缩的配置文件xml

图 2 输入命令

**图 2** 输入命令

单击回车后，运行结果如图3所示。

图 3 运行结果

**图 3** 运行结果

当命令行界面显示“Conversion Success”时，说明该命令已运行完成，进入对应路径下，可查看到生成的.bin文件与头文件（仅在“-p”参数为dir时会生成头文件）。如图4、图5所示。

图 4 生成的bin文件

**图 4** 生成的bin文件

图 5 生成的头文件

**图 5** 生成的头文件

解压模式

解压模式如下：进入到“images_tool.py”文件的保存路径下，并在该路径下运行cmd，在cmd命令行中输入命令“python images_tool.py -d dcmp -e output\ -f output -p file”。如图6所示。

说明： 上述命令中，“-p”后面的输入参数为压缩步骤中填写的参数，若压缩时填写file则解压时也需要填写file，“-e”后面的输入参数对应.bin文件的路径（需要解压的文件路径），“-f”后面的输入参数对应解压图片生成的路径。即：

.bin文件路径：graphic_tools\image_converter_tool\output

图片生成路径：graphic_tools\image_converter_tool\output

图 6 输入命令

**图 6** 输入命令

单击回车后，运行结果如图7所示。

图 7 运行结果

**图 7** 运行结果

当命令行界面显示“Decmpress Success”时，说明该命令已运行完成，进入对应路径下，可查看到生成的图片。如图8所示。

图 8 生成的图片

**图 8** 生成的图片

压缩库说明

图形压缩功能提供了 Android、iOS、Windows 的图形压缩库和 demo，位于 /tools/graphic_tools.tar.gz 归档内的 graphic_tools/CompressDemo。该目录包含 AndroidDemo、WindowsDemo 和 IOSDemo，使用指导见各平台目录下的 ReadMe.txt。

多语言字符串转换工具

多语言字符串转换工具用于将xml信息转换为.lang文件，单板将使用lang文件作为资源支持不同语言字符展示。

转换实例

进入到“language_trans.py”保存路径下，并在该路径下运行cmd，在cmd命令行中输入以下命令，如图1所示。

python language_trans.py test\ output\ include\

说明： 文件输出路径对应的是第二个和第三个输入参数的路径，上述示例命令中两个输入参数相同，因此输出文件会生成在同一路径下。其中：

第二个参数对应路径为.lang文件输出路径。

第三个参数对应路径为.h文件输出路径。

图 1 运行命令

**图 1** 运行命令

运行完成后，进入自定义路径下，可查看到已生成的文件，如图2所示。

图 2 经脚本转换后的输出文件

**图 2** 经脚本转换后的输出文件

离线表盘 XML 转换工具

具体详情请参见UIKit 开发指南的“AOD离线表盘”章节。

获取视频第一帧工具

视频在未加载前，首帧为黑帧，需要用户手动设置一张起始预览图，该工具提供提取视频首帧并将其转换为BMP格式图片的能力。工具位于交付包解压后的“graphic_tools\convert_2_bmp”路径。

转换实例

实例命令如下：

Windows：python .\convert_2_bmp.py -f .\test.mp4 -s 466x466 -o .\output

Linux：python ./convert_2_bmp.py -f ./test.mp4 -s 466x466 -o ./output

Lottie 工具

用于将符合Lottie标准的json文件转化为bin文件。

Linux命令行示例如下
- 单文件处理
  
  ./flatbufferstool input.json output_flatbuffer.bin
- 按路径处理
  
  ./flatbufferstool input output
Windows命令行示例如下
- 单文件处理
  
  flatbufferstool.exe input.json output_flatbuffer.bin
- 按路径处理
  
  flatbufferstool.exe input output

多媒体工具

多媒体工具支持预旋转视频和提取视频首帧；环境配置见FFmpeg，命令与参数见多媒体工具参数与使用方式。

结果校验

图片压缩与解压

压缩命令行显示“Conversion Success”时，压缩操作完成；可在输出路径查看生成的 .bin 文件，在 -p 为 dir 时还会生成资源索引头文件 ui_resource_image.h。
解压命令行显示“Decmpress Success”时，解压操作完成；可在输出路径查看生成的图片。
对应效果示例请参见压缩运行结果和解压运行结果。

多语言、视频与 Lottie 转换

多语言转换完成后，可在自定义输出路径查看每种语言对应的 .lang 文件和头文件 ui_resource_string.h。
视频首帧工具在指定目录生成 .bmp 文件，该文件用于视频浏览帧。
Lottie 工具的输出文件由命令中的输出路径决定；单文件示例输出为 output\_flatbuffer.bin。

多媒体处理

预旋转视频时，工具按配置的参考帧数量将视频转换为 H264 视频；提取视频首帧时，首帧宽高必须与视频匹配。

参数

图片压缩打包工具参数

图片资源打包工具的功能：依据xml文件配置的压缩算法以及像素格式信息，将指定目录下的每一个子目录都打包成一个资源文件并生成资源索引文件“ImageResources.cpp”；工程侧通过资源索引头文件“ui_resource_image.h”引用资源；或者将指定目录下的每一个图片文件都打包成一个资源文件。
命令格式：python images_tool.py -p [dir|file] -d [cmp|dcmp] -c <Config XML> -i <Input Dir> -o <Output Dir> -t <Output Head Dir> -e <Input Dcmp Dir> -f <Output Image Dir>
说明：
- -p：指定打包方式，分别为dir、file两种打包方式。
  - dir：将图片进行打包后，再以子文件夹为单位将其包含的已打包过的图片在一起打包。
  - file：以每个图片为单位进行打包。
- -d：指定压缩、解压模式，分别为cmp、dcmp两种模式。
  - cmp：压缩模式。
  - dcmp：解压模式。
- -c：配置文件，指定打包的压缩算法、像素格式以及非压缩情形下的字节对齐值。
  - 压缩算法可选：NONE|HFBC|HFBC_ABYPASS。
  - 像素格式可选：RGB565|RGB888|ARGB8888。
- -i：指定待处理图片的根目录，图片目录下的图片可以为“.jpg、.png、.bmp”格式。
- -o：指定输出的文件夹。
  
  须知： 如果输出文件夹和输入文件夹不一致，会先删除输出文件夹再创建。
- -t：指定头文件“ui_resource_image.h”生成的目录，仅在dir打包方式下生效。
- -e：指定需要解压的文件的路径，文件类型为“.bin”。
- -f：指定解压后图片输出的路径。
- -rotate：buffer预旋转角度。0：0；1：90；2：180；3：270。
须知：
- 子文件夹名以及文件名必须为数字以及字母的组合。
- 路径支持绝对路径，也支持相对路径。

表 1 XML配置文件参数说明

标签	属性	说明
imageRes	-	imageRes为根标签。
	compress	指定默认打包方式，取值可为：NONE\|HFBC\|HFBC_ABYPASS。
	format	指定默认像素格式，取值可为：RGB565\|RGB888\|ARGB8888。
imageDir	-	imageRes的子标签，用于标识存放图片的文件夹。
	name	文件夹名，可以指定为APP的名字，或者场景名，不与APP强绑定。
	compress	指定该文件夹下的图片文件的默认打包方式，优先级高于imageRes指定的compress属性值。
	format	指定该文件夹下的图片文件的默认像素格式，优先级高于imageRes指定的format属性值。
imageFile	-	imageDir的子标签，用于标识具体某一个文件。
	name	文件名。
	compress	指定特定图片文件的打包方式，优先级高于imageDir指定的compress属性值。
	format	指定特定图片文件的像素格式，优先级高于imageDir指定的format属性值。

XML文件其他参数说明：

tile：压缩单元宽度。4--4x4；6--6x4；8--8x4；16--16x4，也叫压缩倍率在ARGB8888格式时分别对应4倍压缩，6倍压缩，8倍压缩，16倍压缩；在RGB888时分别对应3倍压缩，4.5倍压缩，6倍压缩，12倍压缩；在RGB565时分别对应2倍压缩，3倍压缩，4倍压缩，8倍压缩。
alpha：压缩模式。0：非压缩；1：压缩。
rgb：压缩模式。0：非压缩；1：压缩。
align：宽度对齐。仅在compress为NONE时生效；未填写时脚本按16处理。配置文件中该属性为可选项，请结合实际配置文件和打包方式确认。
autocmpmode：压缩模式。
- 0：手动压缩模式，按照配置文件的配置参数进行压缩。
ver：图片资源格式版本标识。随包配置示例使用1；脚本在ver为1时按包含tile、alpha和rgb的配置处理。配置文件注释将1标注为CS、0标注为ES；但当前随包脚本未对非1配置提供可验证的完整转换流程。需要使用ES配置时，请先使用与项目匹配的工具版本完成转换验证。
dirid：目录资源ID，仅在“-p dir”打包时参与生成资源包及“ui_resource_image.h”。未配置时脚本从1开始；每完成一个非空目录资源包后递增。可填写十进制整数或以0x开头的十六进制整数。生成的资源ID使用高12位保存目录ID、低20位保存图片序号；脚本不会校验取值范围。请使目录ID与单板调用侧一致，并按该位域布局限定在0x0～0xFFF。

须知：

alpha和rgb同时为0是非压缩模式请注意适配。

当rgb压缩模式为0时，alpha的压缩模式不能设置为1。

输入图片的像素大小应小于1280×800。

压缩倍率是与裸数据大小进行对比，而非与源文件大小对比，例如466×466的RGBA图片，无压缩大小为848KB，6倍压缩时为142KB，16倍压缩时大约为54KB。

压缩操作为有损压缩，压缩倍率越大，图损越大。

当compress模式选择为NONE时，由于是纯裸数据无法通过脚本的解压命令还原成原图。

多语言字符串转换工具参数

多语言字符串转换工具的功能：拥有多个语言配置的文件需要生成兼容的多语言二进制文件和头文件。
命令格式：language_trans.py <Xmlpath> <LangPath> <HeadPath>
参数说明：
- XmlPath：xml输出路径。
- LangPath：Language文件bin输出路径。
- HeadPath：头文件输出路径。

获取视频第一帧工具参数

命令格式：python convert_2_bmp.py [-h] -f FILE -s ?x? [-o OUT]

参数说明如下：

-h（--help）：显示工具支持参数。
-f：需要提取的视频文件路径。
-s ?x?：-size [宽]x[高]，指定视频帧的宽高，需要与视频资源一致。
-o OUT：图片生成路径。

多媒体工具参数与使用方式

使用方式

usage: main.py [-h] [-o OUTPUT] (--frame | --rotate) [-s SIZE] [-a {0,1,2,3}] [-r {1,2}] input_path
options:
  -h, --help            show this help message and exit
  --frame               获取视频首帧
  --rotate              顺时针方向旋转视频
公共参数:
  input_path            输入文件路径
  -o OUTPUT, --output OUTPUT
                        输出文件路径
取帧参数:
  仅在使用--frame时有效
  -s SIZE, --size SIZE  提取帧宽*高 (格式: WxH)
旋转参数:
  仅在使用--rotate时有效
  -a {0,1,2,3}, --angle {0,1,2,3}
                        旋转角度, 入参为90为倍数。90:1, 180:2, 270:3
  -r {1,2}, --refs {1,2}
                        参考帧数量

该工具目前支持两种功能：

预旋转视频

在视频不满足显示条件时，参考帧会按照配置的数量，将视频转换为H264的视频。旋转角度的值以90的倍数进行调整。例：python main.py --rotate -a 1 --refs 2 .\input -o .\output
提取视频

如果首帧的宽高与视频不匹配，将转换失败。如果不知道视频帧宽高，可以使用如下命令，例：python main.py --frame -s 0*0 .\input -o .\output

问题处理

Python 环境与模块

图片压缩打包工具和多语言字符串转换工具依赖 Python 环境。所需版本、模块及来源参见Python 环境与模块。

图片压缩打包检查

输出文件夹与输入文件夹不一致时，工具会先删除输出文件夹再创建；请确认输出目录可被清理。
子文件夹名和文件名必须由数字和字母组合。
图片输入格式、像素大小、压缩模式和压缩倍率限制请参见图片压缩打包工具参数。

获取视频第一帧工具注意事项

请使用 Python 3.7 及以上版本；环境配置参见开发环境快速入门。
工具脚本在指定目录生成一个.bmp文件，请使用该文件作为视频浏览帧。不要使用中间生成文件。
调整视频大小可借助ffmpeg工具。例："ffmpeg -i video.mp4 -vf crop=454:454 -b:v 4228k -vcodec mjpeg out.mp4"。
输出只支持YUV420，输入支持YUV420和YUV444。