### Install and use rio-viz

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/Is_it_a_COG.md

Install the rio-viz plugin using pip and then use the `rio viz` command to load and visualize a COG file in a web browser.

```bash
pip install rio-viz
$ rio viz HYP_50M_SR_COG.tif
```

--------------------------------

### Install rio-cogeo with pip

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/index.md

Install the rio-cogeo package using pip. Ensure pip is up-to-date.

```bash
pip install -U pip
pip install rio-cogeo
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/CONTRIBUTING.md

Install pre-commit hooks to ensure code quality and formatting standards are met before committing.

```bash
uv run pre-commit install
```

--------------------------------

### Install rio-cogeo from source

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/index.md

Install the rio-cogeo package directly from its GitHub repository using pip. This is useful for development or when needing the latest unreleased version.

```bash
pip install -U pip
pip install git+https://github.com/cogeotiff/rio-cogeo.git
```

--------------------------------

### Download Sample Data

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/Is_it_a_COG.md

Download a sample raster image from Natural Earth for inspection and COG conversion. This step provides the necessary data to follow along with the examples.

```bash
$ wget https://naciscdn.org/naturalearth/50m/raster/HYP_50M_SR.zip
```

--------------------------------

### GDAL Info Before Forwarding Band Tags

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/Advanced.md

Example output of gdalinfo showing band metadata before using --forward-band-tags.

```bash
$ gdalinfo my_file.tif
...
Band 1 Block=576x1 Type=Float64, ColorInterp=Gray
  NoData Value=999999986991104
  Unit Type: mol mol-1
  Metadata:
    long_name=CO2 Dry-Air Column Average
    missing_value=9.9999999e+14
    NETCDF_DIM_time=0
    NETCDF_VARNAME=XCO2MEAN
    units=mol mol-1
    _FillValue=9.9999999e+14
```

--------------------------------

### Display rio cogeo info help

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/CLI.md

Shows the available options for getting information about a COGEO dataset.

```bash
$ rio cogeo info --help
```

--------------------------------

### GDAL Info After Forwarding Band Tags

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/Advanced.md

Example output of gdalinfo showing band metadata after using --forward-band-tags.

```bash
$ gdalinfo my_cog.tif
...
Band 1 Block=256x256 Type=Float64, ColorInterp=Gray
  NoData Value=999999986991104
  Overviews: 288x181
  Metadata:
    long_name=CO2 Dry-Air Column Average
    missing_value=9.9999999e+14
    NETCDF_DIM_time=0
    NETCDF_VARNAME=XCO2MEAN
    units=mol mol-1
    _FillValue=9.9999999e+14
```

--------------------------------

### Output Progress to Alternative Text Buffer

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/API.md

This example shows how to direct the progress output of `cog_translate` to a file buffer, allowing for background monitoring of translation tasks. The buffer is configured to be interactive to receive progress updates.

```python
from rio_cogeo.cogeo import cog_translate
from rio_cogeo.profiles import cog_profiles

config = {
    "GDAL_NUM_THREADS": "ALL_CPUS",
    "GDAL_TIFF_INTERNAL_MASK": True,
    "GDAL_TIFF_OVR_BLOCKSIZE": "128",
}


with open("logfile.txt", "w+") as buffer:

    # Progress output buffer must be interactive
    buffer.isatty = lambda: True

    cog_translate(
        "example-input.tif",
        "example-output.tif",
        cog_profiles.get("deflate"),
        config=config,
        in_memory=False,
        nodata=0,
        quiet=False,
        progress_out=buffer,
    )
```

--------------------------------

### Get COG information with rio-cogeo

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/Is_it_a_COG.md

Inspect the properties of a COG file, including driver, compression, profile dimensions, georeferencing, and internal overviews (IFDs).

```bash
$ rio cogeo info HYP_50M_SR_COG.tif
```

--------------------------------

### Configure GDAL for cog_validate

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/CHANGES.md

Shows how to pass external GDAL configurations to the `cog_validate` function. This allows control over how external overviews are handled, for example, by disabling their check.

```python
from rio_cogeo import cog_validate

assert cog_validate("cog.tif", congig={"GDAL_DISABLE_READDIR_ON_OPEN": "EMPTY_DIR"})[0]
```

--------------------------------

### Create COG from NumPy Array using MemoryFile

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/API.md

This example shows how to create a COG directly from a NumPy array using `rasterio.io.MemoryFile`. It defines the source profile, writes the array to memory, and then translates it to a COG.

```python
import numpy

import mercantile

from rasterio.io import MemoryFile
from rasterio.transform import from_bounds

from rio_cogeo.cogeo import cog_translate
from rio_cogeo.profiles import cog_profiles

# Create GeoTIFF profile
bounds = mercantile.bounds(mercantile.Tile(0,0,0))

# Rasterio uses numpy array of shape of `(bands, height, width)`
width = 1024
height = 1024
nbands = 3

img_array = tile = numpy.random.rand(nbands, height, width).astype(numpy.float32)

src_transform = from_bounds(*bounds, width=width, height=height)

src_profile = dict(
    driver="GTiff",
    dtype="float32",
    count=nbands,
    height=height,
    width=width,
    crs="epsg:4326",
    transform=src_transform,
)


with MemoryFile() as memfile:
    with memfile.open(**src_profile) as mem:
        # Populate the input file with numpy array
        mem.write(img_array)

        dst_profile = cog_profiles.get("deflate")
        cog_translate(
            mem,
            "my-output-cog.tif",
            dst_profile,
            in_memory=True,
            quiet=True,
        )
```

--------------------------------

### Utility Functions for Raster Data

Source: https://context7.com/cogeotiff/rio-cogeo/llms.txt

Utilize helper functions to check for alpha/mask bands, get non-alpha band indexes, and calculate zoom levels for web tiles. Requires rasterio and morecantile.

```python
import rasterio
from rio_cogeo.utils import (
    has_alpha_band,
    has_mask_band,
    non_alpha_indexes,
    get_zooms,
    get_web_optimized_params,
)
import morecantile

with rasterio.open("input.tif") as src:
    # Check for alpha or mask bands
    print(f"Has alpha band: {has_alpha_band(src)}")
    print(f"Has mask band: {has_mask_band(src)}")

    # Get non-alpha band indexes
    indexes = non_alpha_indexes(src)
    print(f"Non-alpha indexes: {indexes}")

    # Calculate min/max zoom levels for web tiles
    tms = morecantile.tms.get("WebMercatorQuad")
    min_zoom, max_zoom = get_zooms(src, tilesize=256, tms=tms)
    print(f"Zoom range: {min_zoom}-{max_zoom}")

    # Get VRT parameters for web-optimized COG
    web_params = get_web_optimized_params(
        src,
        zoom_level_strategy="auto",
        aligned_levels=2,
        tms=tms,
    )
    print(f"Web-optimized params: {web_params}")
    # {'crs': CRS.from_epsg(3857), 'transform': Affine(...),
    #  'width': 1024, 'height': 1024}
```

--------------------------------

### Set Colormap in cog_translate

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/CHANGES.md

Illustrates how to use the `colormap` option in `cog_translate` to set or update a colormap for a GeoTIFF. The example shows printing a specific colormap entry.

```python
cmap = {0: (0, 0, 0, 0), 1: (1, 2, 3, 255)}
cog_translate("boring.tif", "cogeo.tif", deflate_profile, colormap=cmap)
with rasterio.open("cogeo.tif") as cog:
    print(cog.colormap(1)[1])

>>> (1, 2, 3, 255)
```

--------------------------------

### Get Comprehensive Dataset Information

Source: https://context7.com/cogeotiff/rio-cogeo/llms.txt

Retrieves detailed information about a raster dataset, including validation status, profile metadata, geographic information, and IFD structure. The output can be exported as JSON.

```python
from rio_cogeo.cogeo import cog_info

# Get dataset info
info = cog_info("output_cog.tif")

# Access validation status
print(f"Is valid COG: {info.COG}")
print(f"Driver: {info.Driver}")
print(f"Compression: {info.Compression}")

# Access profile information
print(f"Size: {info.Profile.Width}x{info.Profile.Height}")
print(f"Bands: {info.Profile.Bands}")
print(f"Data type: {info.Profile.Dtype}")
print(f"Tiled: {info.Profile.Tiled}")
print(f"NoData: {info.Profile.Nodata}")

# Access geographic information
print(f"CRS: {info.GEO.CRS}")
print(f"Bounds: {info.GEO.BoundingBox}")
print(f"Zoom range: {info.GEO.MinZoom}-{info.GEO.MaxZoom}")

# Access IFD structure (overviews)
for ifd in info.IFD:
    print(f"Level {ifd.Level}: {ifd.Width}x{ifd.Height}, "
          f"Block: {ifd.Blocksize}, Decimation: {ifd.Decimation}")

# Export as JSON
json_output = info.model_dump_json(exclude_none=True, by_alias=True)
print(json_output)
```

--------------------------------

### Add Additional COG Metadata

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/CHANGES.md

Shows how to use the `additional_cog_metadata` option in `cog_translate` to embed custom metadata, such as comments, into the GeoTIFF tags. The example verifies the tag was added.

```python
cog_translate("boring.tif", "cogeo.tif", deflate_profile, additional_cog_metadata={"comments": "I made this tiff with rio-cogeo"})

with rasterio.open("cogeo.tif") as cog:
    print(cog.tags()["comment"])

>>> "I made this tiff with rio-cogeo"
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/CONTRIBUTING.md

Serve the project documentation locally with hot-reloading enabled.

```bash
uv run mkdocs serve -f docs/mkdocs.yml
```

--------------------------------

### Deploy Documentation

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/CONTRIBUTING.md

Manually deploy the project documentation to GitHub Pages.

```bash
uv run mkdocs gh-deploy -f docs/mkdocs.yml
```

--------------------------------

### Sync Documentation Dependencies

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/CONTRIBUTING.md

Synchronize dependencies required for building and serving documentation using uv.

```bash
git clone https://github.com/cogeotiff/rio-cogeo.git
cd rio-cogeo

uv sync --group docs
```

--------------------------------

### Display rio cogeo create help

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/CLI.md

Shows the available options for creating a Cloud Optimized GeoTIFF.

```bash
$ rio cogeo create --help
```

--------------------------------

### Display rio cogeo help

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/CLI.md

Shows the available commands and options for the rio cogeo CLI.

```bash
$ rio cogeo --help
```

--------------------------------

### Create a COGEO with DEFLATE compression

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/CLI.md

Creates a Cloud Optimized GeoTIFF using the default DEFLATE compression profile.

```bash
# Create a COGEO with DEFLATE compression (Using default `Deflate` profile)
$ rio cogeo create mydataset.tif mydataset_jpeg.tif
```

--------------------------------

### Clone Repository and Sync Dependencies

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/CONTRIBUTING.md

Clone the rio-cogeo repository and synchronize development dependencies using uv.

```bash
git clone https://github.com/cogeotiff/rio-cogeo.git
cd rio-cogeo

uv sync
```

--------------------------------

### cog_info - Get Comprehensive Dataset Information

Source: https://context7.com/cogeotiff/rio-cogeo/llms.txt

Retrieves detailed information about a raster dataset including validation status, profile metadata, geographic information, and IFD (Image File Directory) structure.

```APIDOC
## cog_info - Get Comprehensive Dataset Information

### Description
Retrieves detailed information about a raster dataset including validation status, profile metadata, geographic information, and IFD (Image File Directory) structure.

### Method
```python
from rio_cogeo.cogeo import cog_info
```

### Parameters
#### Path Parameters
- **input_file** (str) - Required - Path to the GeoTIFF file.

#### Query Parameters
- **config** (dict) - Optional - GDAL configuration options.

### Request Example
```python
# Get dataset info
info = cog_info("output_cog.tif")
```

### Response
- **info** (object) - An object containing comprehensive dataset information.
  - **COG** (bool) - Validation status.
  - **Driver** (str) - GDAL driver name.
  - **Compression** (str) - Compression method.
  - **Profile** (object) - Raster profile information.
    - **Width** (int) - Image width.
    - **Height** (int) - Image height.
    - **Bands** (int) - Number of bands.
    - **Dtype** (str) - Data type.
    - **Tiled** (bool) - Whether the image is tiled.
    - **Nodata** (float or None) - No data value.
  - **GEO** (object) - Geographic information.
    - **CRS** (str) - Coordinate Reference System.
    - **BoundingBox** (object) - Bounding box coordinates.
    - **MinZoom** (float) - Minimum zoom level.
    - **MaxZoom** (float) - Maximum zoom level.
  - **IFD** (list) - List of Image File Directory (IFD) objects, representing overviews.
    - **Level** (int) - Overview level.
    - **Width** (int) - Overview width.
    - **Height** (int) - Overview height.
    - **Blocksize** (int) - Block size.
    - **Decimation** (int) - Decimation factor.

### Response Example
```json
{
  "COG": true,
  "Driver": "GTiff",
  "Compression": "LZW",
  "Profile": {
    "Width": 1024,
    "Height": 1024,
    "Bands": 3,
    "Dtype": "float32",
    "Tiled": true,
    "Nodata": null
  },
  "GEO": {
    "CRS": "EPSG:4326",
    "BoundingBox": {
      "left": -180.0,
      "bottom": -90.0,
      "right": 180.0,
      "top": 90.0
    },
    "MinZoom": 0.0,
    "MaxZoom": 10.0
  },
  "IFD": [
    {
      "Level": 1,
      "Width": 512,
      "Height": 512,
      "Blocksize": 256,
      "Decimation": 2
    }
  ]
}
```
```

--------------------------------

### Create COG with Custom Block Size and Overviews

Source: https://context7.com/cogeotiff/rio-cogeo/llms.txt

Creates a COG with custom LZW compression, a specified block size (256x256), and custom overview settings including level and resampling method.

```bash
rio cogeo create input.tif output_cog.tif \
    --cog-profile lzw \
    --blocksize 256 \
    --overview-level 4 \
    --overview-resampling bilinear
```

--------------------------------

### Create Web-Optimized COG with rio-cogeo

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/CHANGES.md

Use the `rio cogeo create` command to generate a web-optimized COG. The `-w` flag enables web optimization. Inspect tags using `rio cogeo info` and `jq`.

```bash
$ rio cogeo create in.tif out.tif -w
$ rio cogeo info out.tif | jq .Tags
```

--------------------------------

### List and Customize Compression Profiles

Source: https://context7.com/cogeotiff/rio-cogeo/llms.txt

Provides access to pre-defined compression profiles for COG creation. Profiles can be listed, retrieved, and customized with specific settings.

```python
from rio_cogeo.profiles import cog_profiles

# List available profiles
print(list(cog_profiles.keys()))
# ['jpeg', 'webp', 'zstd', 'lzw', 'deflate', 'packbits', 'lzma',
#  'lerc', 'lerc_deflate', 'lerc_zstd', 'raw']
```

```python
# Get a profile (returns a copy that can be modified)
deflate_profile = cog_profiles.get("deflate")
print(deflate_profile)
# {'driver': 'GTiff', 'interleave': 'pixel', 'tiled': True,
#  'blockxsize': 512, 'blockysize': 512, 'compress': 'DEFLATE'}
```

```python
# Customize profile settings
jpeg_profile = cog_profiles.get("jpeg")
jpeg_profile.update({
    "blockxsize": 256,
    "blockysize": 256,
    "QUALITY": 85,
    "BIGTIFF": "IF_SAFER",
})
```

```python
# Profile for uncompressed output
raw_profile = cog_profiles.get("raw")
raw_profile.update({
    "blockxsize": 1024,
    "blockysize": 1024,
})
```

--------------------------------

### Calculate Overview Levels (Custom Base)

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/Advanced.md

Calculates overview levels using a custom decimation base. Requires specifying overview_level.

```python
overview_level = 3
decimation_base = 3
overviews = [decimation_base ** j for j in range(1, overview_level + 1)]
print(overviews)
```

```text
[3, 9, 27]
```

--------------------------------

### Create COG with JPEG Compression for RGB

Source: https://context7.com/cogeotiff/rio-cogeo/llms.txt

Creates a COG optimized for RGB imagery using JPEG compression. Specify the band index (e.g., 1,2,3) for the RGB channels.

```bash
rio cogeo create input.tif output_cog.tif --cog-profile jpeg --bidx 1,2,3
```

--------------------------------

### Create COG in Memory for Cloud Upload

Source: https://context7.com/cogeotiff/rio-cogeo/llms.txt

Creates a Cloud Optimized GeoTIFF in memory using `MemoryFile` and then uploads it to an S3 bucket using `boto3`. This avoids writing the COG to local disk before uploading.

```python
# Create COG in memory for cloud upload
import boto3

dst_profile = cog_profiles.get("deflate")

with MemoryFile() as mem_dst:
    cog_translate(
        "input.tif",
        mem_dst.name,
        dst_profile,
        in_memory=True,
        quiet=True,
    )

    # Upload to S3
    client = boto3.client("s3")
    mem_dst.seek(0)
    client.upload_fileobj(mem_dst, "my-bucket", "path/to/output.tif")
```

--------------------------------

### Create a COG with rio-cogeo

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/Is_it_a_COG.md

Use this command to create a Cloud Optimized GeoTIFF with default settings (512x512 blocksize, DEFLATE compression). Ensure the input file exists.

```bash
$ rio cogeo create HYP_50M_SR.tif HYP_50M_SR_COG.tif
```

--------------------------------

### Create a COG using GDAL commands

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/Is_it_a_COG.md

This sequence of GDAL commands achieves the same result as rio-cogeo create, demonstrating the underlying steps for creating a COG.

```bash
$ gdal_translate HYP_50M_SR.tif tmp.tif -co TILED=YES -co COMPRESS=DEFLATE
$ gdaladdo -r nearest tmp.tif 2 4 8 16 32
$ gdal_translate tmp.tif HYP_50M_SR_COG.tif -co TILED=YES -co COMPRESS=DEFLATE -co COPY_SRC_OVERVIEWS=YES
```

--------------------------------

### Create a COGEO with JPEG profile and internal mask

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/CLI.md

Creates a Cloud Optimized GeoTIFF with JPEG compression, specifying bands and adding an internal mask.

```bash
# Create a COGEO with JPEG profile and the first 3 bands of the data and add internal mask
$ rio cogeo create mydataset.tif mydataset_jpeg.tif -b 1,2,3 --add-mask --cog-profile jpeg
```

--------------------------------

### Create Web-Optimized COG with DEFLATE

Source: https://context7.com/cogeotiff/rio-cogeo/llms.txt

Generates a web-optimized COG aligned with web mercator tiles using DEFLATE compression. The '-w' flag enables web optimization.

```bash
rio cogeo create input.tif output_cog.tif -w --cog-profile deflate
```

--------------------------------

### Custom COG Profile Creation

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/profile.md

Create a Cloud Optimized GeoTIFF with custom creation options, such as block size and compression profile, using the `rio cogeo create` command.

```bash
$ rio cogeo create mydataset.tif mydataset_raw.tif --co BLOCKXSIZE=1024 --co BLOCKYSIZE=1024 --cog-profile raw --overview-blocksize 256
```

--------------------------------

### Web-Optimized COG Creation with Python API

Source: https://context7.com/cogeotiff/rio-cogeo/llms.txt

Creates a web-optimized COG using JPEG compression, aligned with the WebMercatorQuad TileMatrixSet. It configures overview resampling, adds a mask, specifies bands, and uses custom GDAL configurations.

```python
import morecantile

tms = morecantile.tms.get("WebMercatorQuad")
output_profile = cog_profiles.get("jpeg")

cog_translate(
    "input.tif",
    "web_optimized_cog.tif",
    output_profile,
    tms=tms,
    zoom_level_strategy="auto",
    aligned_levels=2,
    resampling="bilinear",
    overview_resampling="bilinear",
    add_mask=True,
    indexes=(1, 2, 3),
    config=config,
)
```

--------------------------------

### Calculate Overview Levels (Base 2)

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/Advanced.md

Calculates overview levels using a decimation base of 2. This is the default behavior.

```python
overview_level = 3
overviews = [2 ** j for j in range(1, overview_level + 1)]
print(overviews)
```

```text
[2, 4, 8]
```

--------------------------------

### Create a COG with JPEG compression

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/Is_it_a_COG.md

Create a COG using JPEG compression for significantly smaller file sizes, suitable for visual purposes. Note that JPEG is a lossy compression format.

```bash
$ rio cogeo create HYP_50M_SR.tif HYP_50M_SR_COG_jpeg.tif -p jpeg
```

--------------------------------

### Create COG Forwarding Band Tags

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/Advanced.md

Command to create a COG and forward band metadata tags.

```bash
$ rio cogeo create my_file.tif my_cog.tif --blocksize 256 --forward-band-tags
```

--------------------------------

### Create COG with Blocksize

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/Advanced.md

Command to create a COG with a specified blocksize.

```bash
$ rio cogeo my_file.tif my_cog.tif --blocksize 256
```

--------------------------------

### Create Output COG in Memory and Upload to S3

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/API.md

This snippet demonstrates creating a COG in memory from an existing file and then uploading it to an AWS S3 bucket using `boto3`. It utilizes `rasterio.io.MemoryFile` for intermediate storage.

```python
from rasterio.io import MemoryFile

from rio_cogeo.cogeo import cog_translate
from rio_cogeo.profiles import cog_profiles

from boto3.session import Session as boto3_session

dst_profile = cog_profiles.get("deflate")

with MemoryFile() as mem_dst:
    # Important, we pass `mem_dst.name` as output dataset path
    cog_translate("my-input-file.tif", mem_dst.name, dst_profile, in_memory=True)

    # You can then use the memoryfile to do something else like
    # upload to AWS S3
    client = boto3_session.client("s3")
    client.upload_fileobj(mem_dst, "my-bucket", "my-key")
```

--------------------------------

### Compare file sizes

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/Is_it_a_COG.md

Use the `ls -lah` command to compare the file sizes of the original GeoTIFF and the created COG. This demonstrates the compression benefits.

```bash
$ ls -lah
-rw-r--r--@  1 youpi  staff   167M Oct 18  2014 HYP_50M_SR.tif
-rw-r--r--   1 youpi  staff    58M Jun 12 14:56 HYP_50M_SR_COG.tif
```

--------------------------------

### Translate GeoTIFF to COG with Nodata and Overviews

Source: https://context7.com/cogeotiff/rio-cogeo/llms.txt

Translates a GeoTIFF file to a Cloud Optimized GeoTIFF with specified nodata handling and overview levels. Requires a profile and configuration.

```python
output_profile = cog_profiles.get("lzw")
output_profile.update({
    "blockxsize": 256,
    "blockysize": 256,
})

cog_translate(
    "input.tif",
    "output_cog.tif",
    output_profile,
    nodata=0,
    overview_level=5,
    overview_resampling="average",
    forward_band_tags=True,
    forward_ns_tags=True,
    config=config,
)
```

--------------------------------

### Inspect GeoTIFF Information with rio-cogeo info

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/Is_it_a_COG.md

Use the `rio cogeo info` command to display detailed information about a GeoTIFF file. This includes driver, compression, profile (width, height, bands, tiled status, data type), georeferencing, and IFD structure. Pay attention to 'Tiled' and 'BlockSize' to determine if it meets COG requirements.

```bash
$ rio cogeo info HYP_50M_SR.tif
Driver: GTiff
File: /Users/vincentsarago/Downloads/HYP_50M_SR/HYP_50M_SR.tif
Compression: None
ColorSpace: None

Profile
    Width:            10800
    Height:           5400
    Bands:            3
    Tiled:            False
    Dtype:            uint8
    NoData:           None
    Alpha Band:       False
    Internal Mask:    False
    Interleave:       PIXEL
    ColorMap:         False

Geo
    Crs:              EPSG:4326
    Origin:           (-179.99999999999997, 90.0)
    Resolution:       (0.03333333333333, -0.03333333333333)
    BoundingBox:      (-179.99999999999997, -89.99999999998201, 179.99999999996405, 90.0)

IFD
    Id      Size           BlockSize     Decimation
    0       10800x5400     10800x1       0

```

--------------------------------

### Working with MemoryFile - In-Memory Processing

Source: https://context7.com/cogeotiff/rio-cogeo/llms.txt

Create COGs from numpy arrays or output directly to memory for cloud upload operations.

```APIDOC
## Working with MemoryFile - In-Memory Processing

### Description
Create COGs from numpy arrays or output directly to memory for cloud upload operations.

### Method
Utilizes `rasterio.io.MemoryFile` in conjunction with `rio_cogeo.cogeo.cog_translate`.

### Use Cases
1.  **Create COG from numpy array**: Generate a COG directly from in-memory data.
2.  **Output COG to memory**: Create a COG in memory for subsequent upload to cloud storage or further processing.

### Request Example
```python
import numpy as np
from rasterio.io import MemoryFile
from rasterio.transform import from_bounds
from rio_cogeo.cogeo import cog_translate
from rio_cogeo.profiles import cog_profiles

# --- Create COG from numpy array ---
width, height, nbands = 1024, 1024, 3
bounds = (-180, -90, 180, 90)

# Generate sample data
img_array = np.random.rand(nbands, height, width).astype(np.float32)

src_profile = {
    "driver": "GTiff",
    "dtype": "float32",
    "count": nbands,
    "height": height,
    "width": width,
    "crs": "EPSG:4326",
    "transform": from_bounds(*bounds, width=width, height=height),
}

with MemoryFile() as memfile:
    with memfile.open(**src_profile) as mem:
        mem.write(img_array)

        dst_profile = cog_profiles.get("deflate")
        cog_translate(
            mem,
            "output_from_array.tif",
            dst_profile,
            in_memory=True,
            quiet=True,
        )

# --- Create COG in memory for cloud upload ---
import boto3

dst_profile = cog_profiles.get("deflate")

with MemoryFile() as mem_dst:
    cog_translate(
        "input.tif",
        mem_dst.name,  # Use the name attribute of MemoryFile
        dst_profile,
        in_memory=True,
        quiet=True,
    )

    # Upload to S3
    client = boto3.client("s3")
    mem_dst.seek(0)  # Rewind the file pointer to the beginning
    client.upload_fileobj(mem_dst, "my-bucket", "path/to/output.tif")
```

### Response
This section describes the outcome of in-memory operations. The `cog_translate` function, when `in_memory=True`, writes the COG data to a `MemoryFile` object. This object can then be treated like a file, for example, by uploading its contents to cloud storage.
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/CONTRIBUTING.md

Execute tests using pytest and generate a coverage report.

```bash
uv run pytest --cov rio_cogeo --cov-report term-missing
```

--------------------------------

### Display rio cogeo validate help

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/CLI.md

Shows the available options for validating a Cloud Optimized GeoTIFF.

```bash
$ rio cogeo validate --help
```

--------------------------------

### Compare COG Creation with Small vs. Large Blocksize

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/CHANGES.md

Demonstrates how COG creation behavior changes regarding blocksize and tiling for small images between rio-cogeo versions. Before version 3.5.0, small images were not tiled by default. After 3.5.0, they are tiled with a default blocksize of 512x512.

```bash
# before
rio cogeo create image_51x51.tif cog.tif
rio cogeo info cog.tif --json | jq '.IFD'
>>> [
  {
    "Level": 0,
    "Width": 51,
    "Height": 51,
    "Blocksize": [
      51,
      51
    ],
    "Decimation": 0
  }
]
rio cogeo info cog.tif --json | jq '.Profile.Tiled'
>>> false

# now
rio cogeo create image_51x51.tif cog.tif
rio cogeo info cog.tif --json | jq '.IFD'
>>> [
  {
    "Level": 0,
    "Width": 51,
    "Height": 51,
    "Blocksize": [
      512,
      512
    ],
    "Decimation": 0
  }
]
rio cogeo info cog.tif --json | jq '.Profile.Tiled'
>>> true
```

--------------------------------

### List Raster Info

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/CLI.md

Use the 'rio cogeo info' command to display detailed metadata about a GeoTIFF file. This includes driver, COG status, compression, color space, profile dimensions, georeferencing details, and internal IFD structure with decimation levels.

```bash
$ rio cogeo info mydataset_jpeg.tif
Driver: GTiff
File: mydataset_jpeg.tif
COG: True
Compression: DEFLATE
ColorSpace: None

Profile
    Width:            10980
    Height:           10980
    Bands:            1
    Tiled:            True
    Dtype:            uint16
    NoData:           0.0
    Alpha Band:       False
    Internal Mask:    False
    Interleave:       BAND
    Colormap:         False

Geo
    Crs:              EPSG:32634
    Origin:           (699960.0, 3600000.0)
    Resolution:       (10.0, -10.0)
    BoundingBox:      (699960.0, 3490200.0, 809760.0, 3600000.0)
    MinZoom:          10
    MaxZoom:          19

IFD
    Id      Size           BlockSize     Decimation
    0       10980x10980    1024x1024     0
    1       5490x5490      128x128       2
    2       2745x2745      128x128       4
    3       1373x1373      128x128       8
    4       687x687        128x128       16

```

--------------------------------

### Change in TILING_SCHEME tags

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/CHANGES.md

Metadata tags for tiling schemes have changed from namespaced tags to simple prefixed metadata. Access tags directly using `src.tags()` instead of `src.tags(ns="TILING_SCHEME")`.

```python
import rasterio

# before
with rasterio.open("cog_web.tif") as src:
    print(src.tags(ns="TILING_SCHEME"))
>>> {
    "NAME": "WebMercatorQuad",
    "ZOOM_LEVEL": "18",
}

# now
with rasterio.open("cog_web.tif") as src:
    print(src.tags())
>>> {
    "TILING_SCHEME_NAME": "WebMercatorQuad",
    "TILING_SCHEME_ZOOM_LEVEL": "18",
}
```

--------------------------------

### cog_profiles - Compression Profile Configuration

Source: https://context7.com/cogeotiff/rio-cogeo/llms.txt

Pre-defined compression profiles for Cloud Optimized GeoTIFF creation, providing standardized settings for different compression algorithms.

```APIDOC
## cog_profiles - Compression Profile Configuration

### Description
Pre-defined compression profiles for Cloud Optimized GeoTIFF creation, providing standardized settings for different compression algorithms.

### Method
```python
from rio_cogeo.profiles import cog_profiles
```

### Usage
Access and modify compression profiles.

### Available Profiles
- `jpeg`
- `webp`
- `zstd`
- `lzw`
- `deflate`
- `packbits`
- `lzma`
- `lerc`
- `lerc_deflate`
- `lerc_zstd`
- `raw`

### Request Example
```python
# List available profiles
print(list(cog_profiles.keys()))

# Get a profile (returns a copy that can be modified)
deflate_profile = cog_profiles.get("deflate")

# Customize profile settings
jpeg_profile = cog_profiles.get("jpeg")
jpeg_profile.update({
    "blockxsize": 256,
    "blockysize": 256,
    "QUALITY": 85,
    "BIGTIFF": "IF_SAFER",
})

# Profile for uncompressed output
raw_profile = cog_profiles.get("raw")
raw_profile.update({
    "blockxsize": 1024,
    "blockysize": 1024,
})
```

### Response Example
```python
# Example output of cog_profiles.get("deflate")
{
  "driver": "GTiff",
  "interleave": "pixel",
  "tiled": true,
  "blockxsize": 512,
  "blockysize": 512,
  "compress": "DEFLATE"
}
```
```

--------------------------------

### Update Tiling Scheme Tags

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/release-notes.md

Tiling scheme tags have changed from namespaced tags to simple prefixed metadata. Access them directly using `src.tags()`.

```python
# before
with rasterio.open("cog_web.tif") as src:
    print(src.tags(ns="TILING_SCHEME"))
>>> {
    "NAME": "WebMercatorQuad",
    "ZOOM_LEVEL": "18",
}

# now
with rasterio.open("cog_web.tif") as src:
    print(src.tags())
>>> {
    "TILING_SCHEME_NAME": "WebMercatorQuad",
    "TILING_SCHEME_ZOOM_LEVEL": "18",
}
```

--------------------------------

### Create COG using GDAL's Native COG Driver

Source: https://context7.com/cogeotiff/rio-cogeo/llms.txt

Utilizes GDAL's native COG driver (available in GDAL >= 3.1) for creating Cloud Optimized GeoTIFFs. This can offer performance benefits.

```bash
rio cogeo create input.tif output_cog.tif --use-cog-driver
```

--------------------------------

### COG Info Tags Comparison

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/release-notes.md

Compare the output of `rio cogeo info` before and after updates to see changes in reported COG tags, including Image Metadata, Structure, and Tiling Scheme.

```bash
>>> {
  "AREA_OR_POINT": "Area",
  "OVR_RESAMPLING_ALG": "NEAREST"
}
```

```bash
>> {
  "Image Metadata": {
    "AREA_OR_POINT": "Area",
    "DataType": "Generic",
    "OVR_RESAMPLING_ALG": "NEAREST"
  },
  "Image Structure": {
    "COMPRESSION": "DEFLATE",
    "INTERLEAVE": "BAND",
    "LAYOUT": "COG"
  },
  "Tiling Scheme": {
    "NAME": "WEBMERCATORQUAD",
    "ZOOM_LEVEL": "17"
  }
}
```

--------------------------------

### Create COG with Custom GDAL Configuration and Threads

Source: https://context7.com/cogeotiff/rio-cogeo/llms.txt

Creates a COG while applying custom GDAL configurations, such as setting the number of threads for GDAL operations and controlling output verbosity.

```bash
rio cogeo create input.tif output_cog.tif \
    --config GDAL_NUM_THREADS=4 \
    --threads ALL_CPUS \
    --quiet
```

--------------------------------

### Create COG with Default DEFLATE Compression

Source: https://context7.com/cogeotiff/rio-cogeo/llms.txt

Converts a standard GeoTIFF to COG format using default DEFLATE compression. This is a basic conversion for general-purpose COG creation.

```bash
rio cogeo create input.tif output_cog.tif
```

--------------------------------

### Compare file sizes after JPEG compression

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/Is_it_a_COG.md

Compare the file sizes after applying JPEG compression. This highlights the substantial reduction achieved, though it is a lossy process.

```bash
$ ls -lah
-rw-r--r--@  1 vincentsarago  staff   167M Oct 18  2014 HYP_50M_SR.tif
-rw-r--r--   1 vincentsarago  staff    58M Jun 12 14:56 HYP_50M_SR_COG.tif
-rw-r--r--   1 vincentsarago  staff   4.8M Jun 15 11:08 HYP_50M_SR_COG_jpeg.tif
```

--------------------------------

### COG Info Tags Comparison

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/CHANGES.md

Compares the output of `rio cogeo info` before and after updates, showing the addition of 'Image Metadata', 'Image Structure', and 'Tiling Scheme' sections.

```json
{
  "AREA_OR_POINT": "Area",
  "OVR_RESAMPLING_ALG": "NEAREST"
}
```

```json
{
  "Image Metadata": {
    "AREA_OR_POINT": "Area",
    "DataType": "Generic",
    "OVR_RESAMPLING_ALG": "NEAREST"
  },
  "Image Structure": {
    "COMPRESSION": "DEFLATE",
    "INTERLEAVE": "BAND",
    "LAYOUT": "COG"
  },
  "Tiling Scheme": {
    "NAME": "WEBMERCATORQUAD",
    "ZOOM_LEVEL": "17"
  }
}
```

--------------------------------

### rio cogeo create

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/CLI.md

Creates a Cloud Optimized GeoTIFF (COG) from an input raster file. Allows customization of bands, compression profiles, nodata values, tiling, and resampling algorithms.

```APIDOC
## POST /cogeo/create

### Description
Creates a Cloud Optimized GeoTIFF (COG) from an input raster file. Allows customization of bands, compression profiles, nodata values, tiling, and resampling algorithms.

### Method
CLI COMMAND

### Endpoint
`rio cogeo create INPUT OUTPUT`

### Parameters
#### Path Parameters
- **INPUT** (string) - Required - Path to the input raster file.
- **OUTPUT** (string) - Required - Path for the output COGEO file.

#### Query Parameters
- **--bidx, -b** (list of integers) - Optional - Band indexes to copy.
- **--cog-profile, -p** (string) - Optional - CloudOptimized GeoTIFF profile. Options: `jpeg`, `webp`, `zstd`, `lzw`, `deflate`, `packbits`, `lzma`, `lerc`, `lerc_deflate`, `lerc_zstd`, `raw`. Default: `deflate`.
- **--nodata** (number) - Optional - Set nodata masking values for input dataset.
- **--add-mask** (boolean) - Optional - Force output dataset creation with an internal mask (convert alpha band or nodata to mask).
- **--blocksize** (integer) - Optional - Overwrite profile's tile size.
- **--dtype, -t** (string) - Optional - Output data type. Options: `ubyte`, `uint8`, `uint16`, `int16`, `uint32`, `int32`, `float32`, `float64`.
- **--overview-level** (integer) - Optional - Overview level. If not provided, appropriate overview level will be selected until the smallest overview is smaller than the value of the internal blocksize.
- **--overview-resampling** (string) - Optional - Overview creation resampling algorithm. Options: `nearest`, `bilinear`, `cubic`, `cubic_spline`, `lanczos`, `average`, `mode`, `gauss`. Default: `nearest`.
- **--overview-blocksize** (integer) - Optional - Overview's internal tile size. Default defined by GDAL_TIFF_OVR_BLOCKSIZE env or 128.
- **--web-optimized, -w** (boolean) - Optional - Create COGEO optimized for Web.
- **--zoom-level-strategy** (string) - Optional - Strategy to determine zoom level. Options: `lower`, `upper`, `auto`. Default: `auto`.
- **--zoom-level** (integer) - Optional - Zoom level number for the highest resolution. If specified, `--zoom-level-strategy` is ignored.
- **--aligned-levels** (integer) - Optional - Number of overview levels for which GeoTIFF tile and tiles defined in the tiling scheme match.
- **--resampling, -r** (string) - Optional - Resampling algorithm. Will only be applied with the `--web-optimized` option. Options: `nearest`, `bilinear`, `cubic`, `cubic_spline`, `lanczos`, `average`, `mode`, `max`, `min`, `med`, `q1`, `q3`, `sum`. Default: `nearest`.
- **--in-memory** (boolean) - Optional - Force processing raster in memory.
- **--no-in-memory** (boolean) - Optional - Do not process raster in memory.
- **--allow-intermediate-compression** (boolean) - Optional - Allow intermediate file compression to reduce memory/disk footprint.
- **--forward-band-tags** (boolean) - Optional - Forward band tags to output bands.
- **--forward-ns-tags** (boolean) - Optional - Forward namespaced tags to output dataset.
- **--threads** (integer) - Optional - Number of worker threads for multi-threaded compression. Default: `ALL_CPUS`.
- **--use-cog-driver** (boolean) - Optional - Use GDAL COG Driver (requires GDAL>=3.1).
- **--tms** (string) - Optional - Path to TileMatrixSet JSON file.
- **--co, --profile** (key-value pairs) - Optional - Driver specific creation options. See the documentation for the selected output driver for more information.
- **--config** (key-value pairs) - Optional - GDAL configuration options.
- **--quiet, -q** (boolean) - Optional - Remove progressbar and other non-error output.

### Request Example
```bash
rio cogeo create mydataset.tif mydataset_cog.tif -b 1,2,3 --add-mask --cog-profile jpeg
```

### Response
#### Success Response (200)
- **Output COGEO file** (file) - The created Cloud Optimized GeoTIFF file.

#### Response Example
(No specific response body example provided, output is the file itself)
```

--------------------------------

### Default COG Profiles

Source: https://github.com/cogeotiff/rio-cogeo/blob/main/docs/docs/profile.md

Access the dictionary of default Cloud Optimized GeoTIFF profiles. These profiles define driver, tiling, block sizes, and compression settings.

```python
from rio_cogeo.profiles import cog_profiles

cog_profiles
> {
    'jpeg': {'driver': 'GTiff', 'interleave': 'pixel', 'tiled': True, 'blockxsize': 512, 'blockysize': 512, 'compress': 'JPEG', 'photometric': 'YCbCr'},
    'webp': {'driver': 'GTiff', 'interleave': 'pixel', 'tiled': True, 'blockxsize': 512, 'blockysize': 512, 'compress': 'WEBP'},
    'zstd': {'driver': 'GTiff', 'interleave': 'pixel', 'tiled': True, 'blockxsize': 512, 'blockysize': 512, 'compress': 'ZSTD'},
    'lzw': {'driver': 'GTiff', 'interleave': 'pixel', 'tiled': True, 'blockxsize': 512, 'blockysize': 512, 'compress': 'LZW'},
    'deflate': {'driver': 'GTiff', 'interleave': 'pixel', 'tiled': True, 'blockxsize': 512, 'blockysize': 512, 'compress': 'DEFLATE'}
    'packbits': {'driver': 'GTiff', 'interleave': 'pixel', 'tiled': True, 'blockxsize': 512, 'blockysize': 512, 'compress': 'PACKBITS'},
    'lzma': {'driver': 'GTiff', 'interleave': 'pixel', 'tiled': True, 'blockxsize': 512, 'blockysize': 512, 'compress': 'LZMA'},
    'lerc': {'driver': 'GTiff', 'interleave': 'pixel', 'tiled': True, 'blockxsize': 512, 'blockysize': 512, 'compress': 'LERC'},
    'lerc_deflate': {'driver': 'GTiff', 'interleave': 'pixel', 'tiled': True, 'blockxsize': 512, 'blockysize': 512, 'compress': 'LERC_DEFLATE'},
    'lerc_zstd': {'driver': 'GTiff', 'interleave': 'pixel', 'tiled': True, 'blockxsize': 512, 'blockysize': 512, 'compress': 'LERC_ZSTD'},
    'raw': {'driver': 'GTiff', 'interleave': 'pixel', 'tiled': True, 'blockxsize': 512, 'blockysize': 512}
}
```