和谐浏览图像生成器（HyBIG）。

该存储库包含用于生成浏览图像的代码。其默认行为生成与NASA全球图像浏览服务（GIBS）兼容的图像。

这意味着图像的默认参数是针对与GIBS接口控制文档（ICD）中提出的可视化生成要求和建议相匹配而选择的，该文档可以在Earthdata Wiki上找到，以及其他GIBS文档。

HyBIG可以从GeoTIFF输入图像创建调色板PNG图像和相关元数据。科学参数栅格数据以及RGB[A]栅格图像可以转换为浏览PNG。这些浏览图像通过重投影、平铺和着色进行转换，以无缝集成到GIBS中。

该仓库包含支持HyBIG服务和hybig-py的代码和基础设施。HyBIG服务被打包为Docker容器，部署到NASA的Harmony系统。业务逻辑包含在hybig-py库中，该库在Python脚本中公开了生成浏览图像的函数。

hybig-py

浏览图像生成逻辑封装在hybig-py库中。目前，向用户公开了一个函数，即create_browse。

def create_browse(
    source_tiff: str,
    params: dict = None,
    palette: str | ColorPalette | None = None,
    logger: Logger = None,
) -> list[tuple[Path, Path, Path]]:
    """Create browse imagery from an input geotiff.

    This is the exposed library function to allow users to create browse images
    from the hybig-py library. It parses the input params and constructs the
    correct Harmony input structure [Message.Format] to call the service's
    entry point create_browse_imagery.

    Output images are created and deposited into the input GeoTIFF's directory.

    Args:
        source_tiff: str, location of the input geotiff to process.

        params: [dict | None], A dictionary with the following keys:

            mime: [str], MIME type of the output image (default: 'image/png').
                  any string that contains 'jpeg' will return a jpeg image,
                  otherwise create a png.

            crs: [dict | None], Target image's Coordinate Reference System.
                 A dictionary with 'epsg', 'proj4' or 'wkt' key.

            scale_extent: [dict | None], Scale Extents for the image. This dictionary
                contains "x" and "y" keys each whose value which is a dictionary
                of "min", "max" values in the same units as the crs.
                e.g.: { "x": { "min": 0.5, "max": 125 },
                        "y": { "min": 52, "max": 75.22 } }

            scale_size: [dict | None], Scale sizes for the image.  The dictionary
                contains "x" and "y" keys with the horizontal and veritcal
                resolution in the same units as the crs.
                e.g.: { "x": 10, "y": 10 }

            height: [int | None], height of the output image in gridcells.

            width: [int | none], width of the output image in gridcells.

        palette: [str | ColorPalette | none], either a URL to a remote color palette
             that is fetched and loaded or a ColorPalette object used to color
             the output browse image. If not provided, a grayscale image is
             generated.

        logger: [Logger | None], a configured Logger object. If None a default
             logger will be used.

    Note:
      if supplied, scale_size, scale_extent, height and width must be
      internally consistent.  To define a valid output grid:
            * Specify scale_extent and 1 of:
              * height and width
              * scale_sizes (in the x and y horizontal spatial dimensions)
            * Specify all three of the above, but ensure values are consistent
              with one another, noting that:
              scale_size.x = (scale_extent.x.max - scale_extent.x.min) / width
              scale_size.y = (scale_extent.y.max - scale_extent.y.min) / height

    Returns:
        List of 3-element tuples. These are the file paths of:
        - The output browse image
        - Its associated ESRI world file (containing georeferencing information)
        - The auxiliary XML file (containing duplicative georeferencing information)


    Example Usage:
        results = create_browse(
            "/path/to/geotiff",
            {
                "mime": "image/png",
                "crs": {"epsg": "EPSG:4326"},
                "scale_extent": {
                    "x": {"min": -180, "max": 180},
                    "y": {"min": -90, "max": 90},
                },
                "scale_size": {"x": 10, "y": 10},
            },
            "https://remote-colortable",
            logger,
        )

    """

库安装

hybig-py库可以从PyPI安装，但需要GDAL库作为依赖。确保您有一个具有这些库的环境。您可以在Linux/macOS上检查。

gdal-config --version

在Windows上（如果GDAL在您的PATH中）

gdalinfo --version

一旦验证通过，您就可以简单地安装库

pip install hybig-py

重投影

GIBS期望接收图像在三种坐标参考系统（CRS）投影之一。

区域	代码	名称
北极	EPSG:3413	WGS 84 / NSIDC Sea Ice Polar Stereographic North
南极	EPSG:3031	WGS 84 / Antarctic Polar Stereographic
全球	EPSG:4326	WGS 84 -- WGS84 - 世界大地测量系统1984，用于GPS

HyBIG处理将尝试从输入图像中选择一个GIBS兼容的目标CRS，或从输入中读取它。重投影通过最近邻重采样完成。需要注意的是，HyBig的输出不是科学数据，而是浏览图像，不应用于科学分析。

瓦片

根据与GIBS的协议，大型输出图像被分割成更小、更易于管理和处理的瓦片。HyBIG生成的最大未瓦片图像大小为67,108,864个单元格（8,192 x 8,192）。如果输出图像超过此阈值，HyBIG将自动将输出瓦片成多个4,096 x 4,096单元格的图像。

瓦片图像在其扩展名之前插入基于零的列和行号进行标记。例如，VCF5KYR_1991001_001_2018224205008.r01c02.png代表输出瓦片的第二行第三列。边缘的瓦片被截断以适应整体图像尺寸。目前，您无法覆盖此行为。

着色

HyBIG图像以多种方式着色。可以在输入STAC项目中包含调色板。如果一个项目的资产包含具有palette角色的值，则假定它是对远程颜色表的引用，该表从资产的href中获取并解析为GDAL颜色表。

如果STAC项目缺少颜色信息，则会在Harmony消息源中搜索一个相关URL，其“内容类型”为VisualizationURL，其“类型”为Color Map。如果找到，则假定它是一个远程颜色表，并从该位置获取。

在没有远程颜色信息的情况下，将在输入图像中搜索颜色图，如果存在则使用。

如果找不到颜色信息，则使用灰度。

默认值

HyBIG尝试为浏览图像输出提供GIBS适当的默认值。当用户未提供输出目标值时，HyBIG将尝试选择一个合适的默认值。

坐标参考系统（CRS）

HyBIG从GIBS首选投影列表中选择默认CRS。遵循的步骤简单但有效

1. 如果proj是lonlat，则使用全球（EPSG:4326）
2. 如果投影起始纬度在80° N以上，则使用北方（EPSG:3413）
3. 如果投影起始纬度在-80° N以下，则使用南方（EPSG:3031）
4. 否则使用全局坐标系（EPGS:4326）

比例范围（图像边界）

输出图像的默认比例范围是通过将输入数据边界重新投影到目标坐标系（CRS）来计算的。在重新投影之前，它通过在每个边缘添加21个点（rasterio的默认值）来加密边缘，以考虑由变换产生的非线性边缘，确保输出图像中包含所有数据。

维度/比例大小

输出图像的维度可以显式地包括在harmony消息中的width和height中，也可以根据比例范围和比例大小（分辨率）进行计算。

从比例范围和比例大小进行的维度计算

height = round((scale_extent['ymax'] - scale_extent['ymin']) / scale_size.y)
width = round((scale_extent['xmax'] - scale_extent['xmin']) / scale_size.x)

当一个Harmony消息既不包含dimensions也不包含scaleSizes时，会计算一组默认维度。

对于粗略输入数据，使用分辨率（比例大小）与比例范围一起计算输出维度。对于分辨率高于每网格单元2km的高分辨率数据，使用输入分辨率查找最近的GIBS推荐分辨率（来自ICD的第4.1.8-1和-2表）并使用推荐分辨率与比例范围一起计算输出图像维度。

定制化

用户可以请求对输出图像进行定制，例如在harmony请求中包含crs、scale_extents、scale_sizes或维度（height & width）。然而，生成的输出可能与GIBS不兼容。

当用户定制scale_extent或scale_size时，他们必须在请求中包含一个crs。定制值的单位必须与目标CRS匹配。例如，指定以度为单位的长方形需要目标CRS也以度为单位。

仓库结构

|- 📂 bin
|- 📂 docker
|- 📂 docs
|- 📂 hybig
|- 📂 harmony_service
|- 📂 tests
|- CHANGELOG.md
|- CONTRIBUTING.md
|- LICENSE
|- README.md
|- dev-requirements.txt
|- legacy-CHANGELOG.md
|- pip_requirements.txt
|- pip_requirements_skip_snyk.txt
|- pyproject.toml

• bin - 包含构建服务和测试图像的实用脚本目录。该目录中还包括一个提取最新版本发布说明的脚本，该发布说明包含在CHANGELOG.md中。

• docker - 包含服务和测试图像的Dockerfiles目录。它还包含service_version.txt，其中包含库和服务图像的语义版本号。更新此文件以触发发布。

• docs - 包含示例使用笔记本的目录。

• hybig - 包含HyBIG库的Python源代码目录。此目录包含生成GIBS兼容浏览图像的业务逻辑。

• harmony_service - 包含Harmony服务特定Python代码的目录。adapter.py包含由Harmony服务调用引发的BrowseImageGeneratorAdapter类。

• tests - 包含服务单元测试套件的目录。

• CHANGELOG.md - 此文件包含对HyBIG每个新版本应用的变化记录。任何新版本的发布都应该在此文件中记录更改内容。

• CONTRIBUTING.md - 此文件包含对HyBIG的贡献指南，包括推荐的git最佳实践。

• LICENSE - 根据NASA开源批准分发所必需的。详细说明使用、复制和分发的条件。

• README.md - 此文件，包含开发库和服务的指导。

• dev-requirements.txt - 列出库和服务开发所需的包。

• legacy-CHANGELOG.md - 对之前在EOSDIS内部发布（在代码和Docker图像开源发布之前）的每个版本的注释。

• pip_requirements.txt - 服务Python包依赖项列表。

• pip_requirements_skip_snyk.txt - 一个列表，包含由snyk未扫描漏洞的服务Python包依赖项。此文件仅包含GDAL包。由于snyk的扫描是简单的，无法预先安装所需的库，因此pip install GDAL会失败，我们没有解决方案。

• pyproject.toml - 打包工具以及其他工具（如linters、类型检查器等）使用的配置文件。

本地开发

通过本地实例的Harmony可以本地测试服务功能。请参阅那里有关创建本地Harmony实例的说明。

对于本地开发和测试库修改或与主Harmony应用程序无关的小功能

1. 创建Python虚拟环境
2. 确保GDAL库在虚拟环境中可用。
3. 安装pip_requirements.txt、pip_requirements_skip_snyk.txt和dev-requirements.txt中的依赖项。
4. 安装预提交钩子。

> conda create --name hybig-env python==3.11
> pip install -r pip_requirements.txt -r pip_requirements_skip_snyk.txt
> pip install -r dev-requirements.txt

> pre-commit install

测试

此服务使用Python unittest包对服务中的类和函数执行单元测试。在本地开发完成后，更新测试后，可以通过Docker运行它们

$ ./bin/build-image
$ ./bin/build-test
$ ./bin/run-test

tests/run_tests.sh脚本还会生成一个覆盖率报告（以HTML格式显示），并使用pylint扫描代码。

目前，unittest测试套件在GitHub工作流中自动运行，作为CI/CD管道的一部分。这些测试在针对main分支的PR中进行的所有更改上都运行。必须通过这些测试才能合并PR。

单元测试由GitHub Actions在每次Pull Request时自动执行。

版本控制

Docker服务镜像和hybig-py包库遵循语义版本号：主版本.次版本.修订版。

• 主版本增量：这些是非向后兼容的API更改。
• 次版本增量：这些是向后兼容的API更改。
• 修订版增量：这些更新不会影响服务的API。

CI/CD

HyBIG的CI/CD在GitHub Actions上运行，工作流程位于.github/workflows目录中。

• run_lib_tests.yml - 一个可重用的工作流程，用于测试库函数对支持的Python版本的兼容性。
• run_service_tests.yml - 一个可重用的工作流程，用于构建服务测试Docker镜像，然后在测试Docker容器实例中运行Python单元测试套件。
• run_tests_on_pull_requests.yml - 在对main分支的PR上触发。它运行run_service_tests.yml和run_lib_tests.yml工作流程，以确保新代码通过所有测试。
• publish_docker_image.yml - 在手动触发或对包含更改的main分支提交docker/service_version.txt文件时触发。
• publish_to_pypi.yml - 在手动触发或对包含更改的main分支提交docker/service_version.txt文件时触发。
• publish_release.yml - 当主分支上的docker/service_version.txt文件有更改时，此工作流程会自动运行。此工作流程将
  • 运行完整的单元测试套件，以防止发布损坏的代码。
  • 从docker/service_version.txt中提取语义版本号。
  • 从CHANGELOG.md中提取最新版本的发布说明。
  • 构建并部署服务Docker镜像到ghcr.io。
  • 构建要发布到PyPI的库包。
  • 将包发布到PyPI。
  • 根据语义版本号在GitHub发行版下发布，并带有相关的git标签。

发布

一个发布包括发布到PyPI的新hybig-py库和一个发布到GitHub容器存储库的新Docker服务镜像。

当主分支上的提交包含对docker/service_version.txt文件的更改时，会自动创建发布，请参阅CI/CD部分上方的publish_release工作流程。

在合并会触发发布的PR之前，请确保这两份文件已更新

• CHANGELOG.md - 应添加备注以记录服务变更。
• docker/service_version.txt - 应更新语义版本号。

CHANGELOG.md 文件需要一个特定格式以供新版本发布使用，因为它会查找以下字符串来定义代码的最新版本（从文件顶部开始）。

## [vX.Y.Z] - YYYY-MM-DD

在文件底部按现有模式更新markdown引用。

[unreleased]:https://github.com/nasa/harmony-browse-image-generator/compare/X.Y.Z..HEAD
[vX.Y.Z]:https://github.com/nasa/harmony-browse-image-generator/compare/X.Y.Y..X.Y.Z

pre-commit钩子

该仓库使用pre-commit来启用预提交检查，确保仓库符合一些编码规范的最佳实践。这包括

• 移除尾部空格。
• 移除文件末尾的空白行。
• JSON文件具有有效的格式。
• ruff Python代码检查。
• black Python代码格式化检查。

要本地启用这些检查

# Install pre-commit Python package as part of test requirements:
pip install -r tests/pip_test_requirements.txt

# Install the git hook scripts:
pre-commit install

# (Optional) Run against all files:
pre-commit run --all-files

当您尝试在本地进行新提交时，pre-commit将自动运行。如果任何钩子检测到不符合规范（例如，尾部空格），该钩子将声明失败，并尝试修复问题。您需要在提交之前审查并使用git add更改。

计划实施额外的钩子，可能包括如mypy等工具。

pre-commit.ci已配置，以便为每个pull request自动运行这些相同的钩子。

发布新版本的服务

一旦发布了带有新语义版本标签的新Docker镜像，就可以按照Harmony管理现有服务指南中的说明，将该服务版本发布到Harmony环境。

联系信息

您可以通过电子邮件联系此仓库的维护者

• david.p.auty@nasa.gov
• matthew.savoie@colorado.edu
• owen.m.littlejohns@nasa.gov