DGGS to Geo

DGGS to Geographic coordinate conversion functions.

This module provides functions to convert various discrete global grid systems (DGGS) to shapely polygon and geojson.

a52geo_cli()

Command-line interface for a52geo supporting multiple a5 cell IDs.

Source code in vgrid/conversion/dggs2geo/a52geo.py

def a52geo_cli():
    """
    Command-line interface for a52geo supporting multiple a5 cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert a5 cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "a5",
        nargs="+",
        help="Input a5 cell ID(s), e.g., a52geo 8e65b56628e0d07 8e65b56628e6adf",
    )
    parser.add_argument(
        "-split",
        "--split_antimeridian",
        action="store_true",
        default=True,
        help="Apply antimeridian fixing to the resulting polygons",
    )
    args = parser.parse_args()
    polys = a52geo(args.a5, split_antimeridian=args.split_antimeridian)
    return polys

a52geojson(a5_hexes, options=None, split_antimeridian=False)

Convert A5 cell IDs to GeoJSON FeatureCollection.

Accepts a single a5_id (string or int) or a list of a5_ids. For each valid A5 cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

a5_hexes : str, int, or list of str/int A5 cell ID(s) to convert. Can be a single string/int or a list of strings/ints. Example format: "8e65b56628e0d07" options : dict, optional Options to pass to a5.cell_to_boundary. Defaults to None. split_antimeridian : bool, optional When True, apply antimeridian fixing to the resulting polygons. Defaults to False when None or omitted.

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid A5 cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the A5 cell ID, resolution level, and cell metadata

Examples

a52geojson("8e65b56628e0d07")

a52geojson(["8e65b56628e0d07", "8e65b56628e6adf"])

Source code in vgrid/conversion/dggs2geo/a52geo.py

def a52geojson(a5_hexes, options=None, split_antimeridian=False):
    """
    Convert A5 cell IDs to GeoJSON FeatureCollection.

    Accepts a single a5_id (string or int) or a list of a5_ids. For each valid A5 cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    a5_hexes : str, int, or list of str/int
        A5 cell ID(s) to convert. Can be a single string/int or a list of strings/ints.
        Example format: "8e65b56628e0d07"
    options : dict, optional
        Options to pass to a5.cell_to_boundary. Defaults to None.
    split_antimeridian : bool, optional
        When True, apply antimeridian fixing to the resulting polygons.
        Defaults to False when None or omitted.

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid A5 cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the A5 cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> a52geojson("8e65b56628e0d07")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> a52geojson(["8e65b56628e0d07", "8e65b56628e6adf"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    # Handle single input (string or int)
    if isinstance(a5_hexes, str):
        a5_hexes = [a5_hexes]

    a5_features = []
    for a5_hex in a5_hexes:
        try:
            cell_polygon = a52geo(
                a5_hex, options, split_antimeridian=split_antimeridian
            )
            num_edges = 5
            resolution = a5.get_resolution(a5.hex_to_u64(a5_hex))
            a5_feature = geodesic_dggs_to_feature(
                "a5", a5_hex, resolution, cell_polygon, num_edges
            )
            a5_features.append(a5_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": a5_features}

a52geojson_cli()

Command-line interface for a52geojson supporting multiple A5 cell hex.

Source code in vgrid/conversion/dggs2geo/a52geo.py

def a52geojson_cli():
    """
    Command-line interface for a52geojson supporting multiple A5 cell hex.
    """
    parser = argparse.ArgumentParser(description="Convert A5 cell hex to GeoJSON")
    parser.add_argument(
        "a5",
        nargs="+",
        help="Input a5 cell hex, e.g., a52geojson 8e65b56628e0d07 8e65b56628e6adf",
    )
    parser.add_argument(
        "-split",
        "--split_antimeridian",
        action="store_true",
        default=False,
        help="Enable Antimeridian splitting",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(
        a52geojson(args.a5, split_antimeridian=args.split_antimeridian)
    )
    print(geojson_data)

dggal2geojson(dggs_type, zone_ids, options={}, split_antimeridian=False)

Convert DGGAL ZoneIDs to GeoJSON FeatureCollection.

Accepts a single zone_id (string) or a list of zone_ids. For each valid DGGAL ZoneID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

dggs_type : str DGGAL DGGS type (e.g., "isea3h", "isea4t", "rhealpix"). zone_ids : str or list of str DGGAL ZoneID(s) to convert. Can be a single string or a list of strings. Example format: "A4-0-A" options : dict, optional Additional options for the conversion process. split_antimeridian : bool, optional When True, apply antimeridian fixing to the resulting polygons. Defaults to False when None or omitted.

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid DGGAL cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the DGGAL ZoneID, resolution level, and cell metadata

Examples

dggal2geojson("isea3h", "A4-0-A")

dggal2geojson("isea3h", ["A4-0-A", "A4-0-B"])

Source code in vgrid/conversion/dggs2geo/dggal2geo.py

def dggal2geojson(
    dggs_type: str, zone_ids: str, options: dict = {}, split_antimeridian=False
):
    """
    Convert DGGAL ZoneIDs to GeoJSON FeatureCollection.

    Accepts a single zone_id (string) or a list of zone_ids. For each valid DGGAL ZoneID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    dggs_type : str
        DGGAL DGGS type (e.g., "isea3h", "isea4t", "rhealpix").
    zone_ids : str or list of str
        DGGAL ZoneID(s) to convert. Can be a single string or a list of strings.
        Example format: "A4-0-A"
    options : dict, optional
        Additional options for the conversion process.
    split_antimeridian : bool, optional
        When True, apply antimeridian fixing to the resulting polygons.
        Defaults to False when None or omitted.

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid DGGAL cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the DGGAL ZoneID, resolution level, and cell metadata

    Examples
    --------
    >>> dggal2geojson("isea3h", "A4-0-A")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> dggal2geojson("isea3h", ["A4-0-A", "A4-0-B"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    dggs_type = validate_dggal_type(dggs_type)
    # Create the appropriate DGGS instance
    dggs_class_name = DGGAL_TYPES[dggs_type]["class_name"]
    dggrs = globals()[dggs_class_name]()

    if isinstance(zone_ids, str):
        zone_ids = [zone_ids]
    zone_features = []

    for zone_id in zone_ids:
        try:
            zone = dggrs.getZoneFromTextID(zone_id)
            resolution = dggrs.getZoneLevel(zone)
            num_edges = dggrs.countZoneEdges(zone)
            cell_polygon = dggal2geo(
                dggs_type, zone_id, options, split_antimeridian=split_antimeridian
            )
            zone_feature = geodesic_dggs_to_feature(
                f"dggal_{dggs_type}", zone_id, resolution, cell_polygon, num_edges
            )
            zone_features.append(zone_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": zone_features}

dggal2geojson_cli()

Command-line interface for converting DGGAL ZoneIDs to GeoJSON.

This function provides a command-line interface that accepts multiple DGGAL ZoneIDs as command-line arguments and outputs the corresponding GeoJSON FeatureCollection as a JSON string to stdout.

Usage

dggal2geojson isea3h A4-0-A A4-0-B

Output

Prints a JSON string representing a GeoJSON FeatureCollection to stdout.

Example

$ python -m vgrid.conversion.dggs2geo.dggal2geo isea3h A4-0-A

Note

This function is designed to be called from the command line and will parse arguments using argparse. The GeoJSON output is formatted as a JSON string printed to stdout. Invalid cell IDs are silently skipped.

Source code in vgrid/conversion/dggs2geo/dggal2geo.py

def dggal2geojson_cli():
    """
    Command-line interface for converting DGGAL ZoneIDs to GeoJSON.

    This function provides a command-line interface that accepts multiple DGGAL
    ZoneIDs as command-line arguments and outputs the corresponding GeoJSON
    FeatureCollection as a JSON string to stdout.

    Usage:
        dggal2geojson isea3h A4-0-A A4-0-B

    Output:
        Prints a JSON string representing a GeoJSON FeatureCollection to stdout.

    Example:
        $ python -m vgrid.conversion.dggs2geo.dggal2geo isea3h A4-0-A
        {"type": "FeatureCollection", "features": [...]}

    Note:
        This function is designed to be called from the command line and will
        parse arguments using argparse. The GeoJSON output is formatted as a
        JSON string printed to stdout. Invalid cell IDs are silently skipped.
    """
    parser = argparse.ArgumentParser(description="Convert DGGAL ZoneID(s) to GeoJSON")
    parser.add_argument(
        "dggs_type", type=str, choices=DGGAL_TYPES.keys(), help="DGGAL DGGS type"
    )
    parser.add_argument(
        "zone_id",
        nargs="+",
        help="Input DGGAL ZoneID(s), e.g., dggal2geojson isea3h A4-0-A A4-0-B",
    )
    parser.add_argument(
        "-split",
        "--split_antimeridian",
        action="store_true",
        default=False,
        help="Enable Antimeridian splitting",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(
        dggal2geojson(
            args.dggs_type, args.zone_id, split_antimeridian=args.split_antimeridian
        )
    )
    print(geojson_data)  # print to stdout

dggrid2geo_cli()

Command-line interface for dggrid2geo supporting multiple DGGRID cell IDs.

Source code in vgrid/conversion/dggs2geo/dggrid2geo.py

def dggrid2geo_cli():
    """
    Command-line interface for dggrid2geo supporting multiple DGGRID cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert DGGRID cell ID(s) to Shapely Polygons. \
                                     Usage: dggrid2geo <cell_ids> <dggs_type> <res> [input_address_type]. \
                                     Ex: dggrid2geo 783229476878 ISEA7H 13 SEQNUM"
    )
    parser.add_argument(
        "dggs_type",
        choices=dggs_types,
        help="Select a DGGS type from the available options.",
    )

    parser.add_argument("dggrid_ids", nargs="+", help="Input DGGRID cell ID(s)")

    parser.add_argument("resolution", type=int, help="resolution")
    parser.add_argument(
        "input_address_type",
        choices=output_address_types,
        default="SEQNUM",
        nargs="?",  # This makes the argument optional
        help="Select an input address type from the available options.",
    )

    parser.add_argument(
        "-split",
        "--split_antimeridian",
        action="store_true",
        default=False,
        help="Apply antimeridian fixing to the resulting polygons",
    )
    parser.add_argument(
        "-aggregate",
        "--aggregate",
        action="store_true",
        help="Aggregate the resulting polygons",
    )
    args = parser.parse_args()
    dggrid_instance = create_dggrid_instance()
    polys = dggrid2geo(
        dggrid_instance,
        args.dggs_type,
        args.dggrid_ids,
        args.resolution,
        args.input_address_type,
        split_antimeridian=args.split_antimeridian,
        aggregate=args.aggregate,
    )
    return polys

dggrid2geojson(dggrid_instance, dggs_type, dggrid_ids, resolution, input_address_type='SEQNUM', split_antimeridian=False, aggregate=False)

Convert DGGRID cell IDs to GeoJSON FeatureCollection.

Accepts a single dggrid_id (string/int) or a list of dggrid_ids. For each valid DGGRID cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

dggrid_instance : object DGGRID instance for processing. dggs_type : str DGGRID DGGS type (e.g., "ISEA7H", "ISEA4T"). dggrid_ids : str, int, or list of str/int DGGRID cell ID(s) to convert. Can be a single string/int or a list of strings/ints. Example format: "783229476878" resolution : int Resolution level for the DGGS. input_address_type : str, default "SEQNUM" Input address type for the cell IDs. split_antimeridian : bool, optional When True, apply antimeridian fixing to the resulting polygons. Defaults to False when None or omitted.

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid DGGRID cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the DGGRID cell ID, resolution level, and cell metadata

Examples

dggrid2geojson(instance, "ISEA7H", "783229476878", 13)

dggrid2geojson(instance, "ISEA7H", ["783229476878", "783229476879"], 13)

Source code in vgrid/conversion/dggs2geo/dggrid2geo.py

def dggrid2geojson(
    dggrid_instance,
    dggs_type,
    dggrid_ids,
    resolution,
    input_address_type="SEQNUM",
    split_antimeridian=False,
    aggregate=False,
):
    """
    Convert DGGRID cell IDs to GeoJSON FeatureCollection.

    Accepts a single dggrid_id (string/int) or a list of dggrid_ids. For each valid DGGRID cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    dggrid_instance : object
        DGGRID instance for processing.
    dggs_type : str
        DGGRID DGGS type (e.g., "ISEA7H", "ISEA4T").
    dggrid_ids : str, int, or list of str/int
        DGGRID cell ID(s) to convert. Can be a single string/int or a list of strings/ints.
        Example format: "783229476878"
    resolution : int
        Resolution level for the DGGS.
    input_address_type : str, default "SEQNUM"
        Input address type for the cell IDs.
    split_antimeridian : bool, optional
        When True, apply antimeridian fixing to the resulting polygons.
        Defaults to False when None or omitted.

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid DGGRID cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the DGGRID cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> dggrid2geojson(instance, "ISEA7H", "783229476878", 13)
    {'type': 'FeatureCollection', 'features': [...]}

    >>> dggrid2geojson(instance, "ISEA7H", ["783229476878", "783229476879"], 13)
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(dggrid_ids, (str, int)):
        dggrid_ids = [dggrid_ids]

    # Get the GeoDataFrame from dggrid2geo
    gdf = dggrid2geo(
        dggrid_instance,
        dggs_type,
        dggrid_ids,
        resolution,
        input_address_type,
        split_antimeridian=split_antimeridian,
        aggregate=aggregate,
    )
    # Convert GeoDataFrame to GeoJSON dictionary
    geojson_dict = json.loads(gdf.to_json())

    return geojson_dict

dggrid2geojson_cli()

Command-line interface for dggrid2geojson supporting multiple DGGRID cell IDs.

Source code in vgrid/conversion/dggs2geo/dggrid2geo.py

def dggrid2geojson_cli():
    """
    Command-line interface for dggrid2geojson supporting multiple DGGRID cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert DGGRID cell ID(s) to GeoJSON. \
                                     Usage: dggrid2geojson <cell_ids> <dggs_type> <res> [input_address_type]. \
                                     Ex: dggrid2geojson 783229476878 ISEA7H 13 SEQNUM"
    )

    parser.add_argument(
        "dggs_type",
        choices=dggs_types,
        help="Select a DGGS type from the available options.",
    )
    parser.add_argument("dggrid_ids", nargs="+", help="Input DGGRID cell ID(s)")
    parser.add_argument("resolution", type=int, help="resolution")
    parser.add_argument(
        "input_address_type",
        choices=output_address_types,
        default="SEQNUM",
        nargs="?",  # This makes the argument optional
        help="Select an input address type from the available options.",
    )
    parser.add_argument(
        "-split",
        "--split_antimeridian",
        action="store_true",
        default=True,
        help="Enable Antimeridian splitting",
    )
    parser.add_argument(
        "-aggregate",
        "--aggregate",
        action="store_true",
        help="Aggregate the resulting polygons",
    )
    args = parser.parse_args()
    dggrid_instance = create_dggrid_instance()
    geojson_data = json.dumps(
        dggrid2geojson(
            dggrid_instance,
            args.dggs_type,
            args.dggrid_ids,
            args.resolution,
            args.input_address_type,
            split_antimeridian=args.split_antimeridian,
            aggregate=args.aggregate,
        )
    )
    print(geojson_data)

digipin2geo_cli()

Command-line interface for digipin2geo supporting multiple DIGIPIN codes.

Source code in vgrid/conversion/dggs2geo/digipin2geo.py

def digipin2geo_cli():
    """
    Command-line interface for digipin2geo supporting multiple DIGIPIN codes.
    """
    parser = argparse.ArgumentParser(
        description="Convert DIGIPIN code(s) to Shapely Polygons"
    )
    parser.add_argument(
        "digipin_id", nargs="+", help="Input DIGIPIN code(s), e.g. F3K 39J-438-TJC7"
    )
    args = parser.parse_args()
    polys = digipin2geo(args.digipin_id)
    return polys

digipin2geojson(digipin_ids)

Convert DIGIPIN cell IDs to GeoJSON FeatureCollection.

Accepts a single digipin_id (string) or a list of digipin_ids. For each valid DIGIPIN cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

digipin_ids : str or list of str DIGIPIN cell ID(s) to convert. Can be a single string or a list of strings. Format: Alphanumeric code with optional dashes (e.g., 'F3K-492-6P96' or 'F3K4926P96') DIGIPIN codes represent locations in India (lat: 2.5-38.5, lon: 63.5-99.5)

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid DIGIPIN cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the DIGIPIN cell ID, resolution level, and cell metadata

Examples

digipin2geojson("F3K")

digipin2geojson(["F3K", "39J-438-TJC7"])

Source code in vgrid/conversion/dggs2geo/digipin2geo.py

def digipin2geojson(digipin_ids):
    """
    Convert DIGIPIN cell IDs to GeoJSON FeatureCollection.

    Accepts a single digipin_id (string) or a list of digipin_ids. For each valid DIGIPIN cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    digipin_ids : str or list of str
        DIGIPIN cell ID(s) to convert. Can be a single string or a list of strings.
        Format: Alphanumeric code with optional dashes (e.g., 'F3K-492-6P96' or 'F3K4926P96')
        DIGIPIN codes represent locations in India (lat: 2.5-38.5, lon: 63.5-99.5)

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid DIGIPIN cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the DIGIPIN cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> digipin2geojson("F3K")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> digipin2geojson(["F3K", "39J-438-TJC7"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(digipin_ids, str):
        digipin_ids = [digipin_ids]
    digipin_features = []
    for digipin_id in digipin_ids:
        try:
            bounds = digipin_to_bounds(digipin_id)
            if isinstance(bounds, str):  # Error message like 'Invalid DIGIPIN'
                continue
            min_lat = bounds["minLat"]
            max_lat = bounds["maxLat"]
            min_lon = bounds["minLon"]
            max_lon = bounds["maxLon"]
            cell_polygon = Polygon(
                [
                    [min_lon, min_lat],
                    [max_lon, min_lat],
                    [max_lon, max_lat],
                    [min_lon, max_lat],
                    [min_lon, min_lat],
                ]
            )
            # Calculate resolution from DIGIPIN code length (excluding dashes)
            clean_id = digipin_id.replace("-", "")
            resolution = len(clean_id)
            digipin_feature = graticule_dggs_to_feature(
                "digipin_id", digipin_id, resolution, cell_polygon
            )
            digipin_features.append(digipin_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": digipin_features}

digipin2geojson_cli()

Command-line interface for digipin2geojson supporting multiple DIGIPIN codes.

Source code in vgrid/conversion/dggs2geo/digipin2geo.py

def digipin2geojson_cli():
    """
    Command-line interface for digipin2geojson supporting multiple DIGIPIN codes.
    """
    parser = argparse.ArgumentParser(description="Convert DIGIPIN code(s) to GeoJSON")
    parser.add_argument(
        "digipin_id", nargs="+", help="Input DIGIPIN code(s), e.g. F3K 39J-438-TJC7"
    )
    args = parser.parse_args()
    geojson_data = json.dumps(digipin2geojson(args.digipin_id))
    print(geojson_data)

ease2geo_cli()

Command-line interface for ease2geo supporting multiple EASE-DGGS codes.

Source code in vgrid/conversion/dggs2geo/ease2geo.py

def ease2geo_cli():
    """
    Command-line interface for ease2geo supporting multiple EASE-DGGS codes.
    """
    parser = argparse.ArgumentParser(
        description="Convert EASE-DGGS code(s) to Shapely Polygons"
    )
    parser.add_argument(
        "ease",
        nargs="+",
        help="Input EASE-DGGS code(s), e.g., ease2geo L4.165767.02.02.20.71 ...",
    )
    args = parser.parse_args()
    polys = ease2geo(args.ease)
    return polys

ease2geojson(ease_ids)

Convert a list of EASE-DGGS codes to GeoJSON FeatureCollection.

Accepts a single ease_id (string) or a list of ease_ids. For each valid EASE-DGGS code, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

ease_ids : str or list of str EASE-DGGS code(s) to convert. Can be a single string or a list of strings. Example format: "L4.165767.02.02.20.71"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid EASE-DGGS cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the EASE-DGGS code, resolution level, and cell metadata

Examples

ease2geojson("L4.165767.02.02.20.71")

ease2geojson(["L4.165767.02.02.20.71", "L4.165768.02.02.20.71"])

Source code in vgrid/conversion/dggs2geo/ease2geo.py

def ease2geojson(ease_ids):
    """
    Convert a list of EASE-DGGS codes to GeoJSON FeatureCollection.

    Accepts a single ease_id (string) or a list of ease_ids. For each valid EASE-DGGS code,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    ease_ids : str or list of str
        EASE-DGGS code(s) to convert. Can be a single string or a list of strings.
        Example format: "L4.165767.02.02.20.71"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid EASE-DGGS cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the EASE-DGGS code, resolution level, and cell metadata

    Examples
    --------
    >>> ease2geojson("L4.165767.02.02.20.71")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> ease2geojson(["L4.165767.02.02.20.71", "L4.165768.02.02.20.71"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(ease_ids, str):
        ease_ids = [ease_ids]
    ease_features = []
    for ease_id in ease_ids:
        try:
            cell_polygon = ease2geo(ease_id)
            resolution = get_ease_resolution(ease_id)
            num_edges = 4
            ease_feature = geodesic_dggs_to_feature(
                "ease", ease_id, resolution, cell_polygon, num_edges
            )
            ease_features.append(ease_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": ease_features}

ease2geojson_cli()

Command-line interface for ease2geojson supporting multiple EASE-DGGS codes.

Source code in vgrid/conversion/dggs2geo/ease2geo.py

def ease2geojson_cli():
    """
    Command-line interface for ease2geojson supporting multiple EASE-DGGS codes.
    """
    parser = argparse.ArgumentParser(description="Convert EASE-DGGS code(s) to GeoJSON")
    parser.add_argument(
        "ease",
        nargs="+",
        help="Input EASE-DGGS code(s), e.g., ease2geojson L4.165767.02.02.20.71 ...",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(ease2geojson(args.ease))
    print(geojson_data)

gars2geo_cli()

Command-line interface for gars2geo supporting multiple GARS cell IDs.

Source code in vgrid/conversion/dggs2geo/gars2geo.py

def gars2geo_cli():
    """
    Command-line interface for gars2geo supporting multiple GARS cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert GARS cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "gars",
        nargs="+",
        help="Input GARS cell ID(s), e.g., gars2geo 574JK1918 ...",
    )
    args = parser.parse_args()
    polys = gars2geo(args.gars)
    return polys

gars2geojson(gars_ids)

Convert GARS cell IDs to GeoJSON FeatureCollection.

Accepts a single gars_id (string) or a list of gars_ids. For each valid GARS cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

gars_ids : str or list of str GARS cell ID(s) to convert. Can be a single string or a list of strings. Example format: "574JK1918"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid GARS cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the GARS cell ID, resolution level, and cell metadata

Examples

gars2geojson("574JK1918")

gars2geojson(["574JK1918", "574JK1919"])

Source code in vgrid/conversion/dggs2geo/gars2geo.py

def gars2geojson(gars_ids):
    """
    Convert GARS cell IDs to GeoJSON FeatureCollection.

    Accepts a single gars_id (string) or a list of gars_ids. For each valid GARS cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    gars_ids : str or list of str
        GARS cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "574JK1918"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid GARS cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the GARS cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> gars2geojson("574JK1918")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> gars2geojson(["574JK1918", "574JK1919"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(gars_ids, str):
        gars_ids = [gars_ids]
    gars_features = []
    for gars_id in gars_ids:
        try:
            gars_grid = garsgrid.GARSGrid(gars_id)
            wkt_polygon = gars_grid.polygon
            resolution_minute = gars_grid.resolution
            resolution = 1
            if resolution_minute == 30:
                resolution = 1
            elif resolution_minute == 15:
                resolution = 2
            elif resolution_minute == 5:
                resolution = 3
            elif resolution_minute == 1:
                resolution = 4
            cell_polygon = Polygon(list(wkt_polygon.exterior.coords))
            gars_feature = graticule_dggs_to_feature(
                "gars", gars_id, resolution, cell_polygon
            )
            gars_features.append(gars_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": gars_features}

gars2geojson_cli()

Command-line interface for gars2geojson supporting multiple GARS cell IDs.

Source code in vgrid/conversion/dggs2geo/gars2geo.py

def gars2geojson_cli():
    """
    Command-line interface for gars2geojson supporting multiple GARS cell IDs.
    """
    parser = argparse.ArgumentParser(description="Convert GARS cell ID(s) to GeoJSON")
    parser.add_argument(
        "gars",
        nargs="+",
        help="Input GARS cell ID(s), e.g., gars2geojson 574JK1918 ...",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(gars2geojson(args.gars))
    print(geojson_data)

geohash2geo_cli()

Command-line interface for geohash2geo supporting multiple Geohash cell IDs.

Source code in vgrid/conversion/dggs2geo/geohash2geo.py

def geohash2geo_cli():
    """
    Command-line interface for geohash2geo supporting multiple Geohash cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert Geohash cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "geohash",
        nargs="+",
        help="Input Geohash cell ID(s), e.g., geohash2geo w3gvk1td8 ...",
    )
    args = parser.parse_args()
    polys = geohash2geo(args.geohash)
    return polys

geohash2geojson(geohash_ids)

Convert Geohash cell IDs to GeoJSON FeatureCollection.

Accepts a single geohash_id (string) or a list of geohash_ids. For each valid Geohash cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

geohash_ids : str or list of str Geohash cell ID(s) to convert. Can be a single string or a list of strings. Example format: "w3gvk1td8"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid Geohash cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the Geohash cell ID, resolution level, and cell metadata

Examples

geohash2geojson("w3gvk1td8")

geohash2geojson(["w3gvk1td8", "w3gvk1td9"])

Source code in vgrid/conversion/dggs2geo/geohash2geo.py

def geohash2geojson(geohash_ids):
    """
    Convert Geohash cell IDs to GeoJSON FeatureCollection.

    Accepts a single geohash_id (string) or a list of geohash_ids. For each valid Geohash cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    geohash_ids : str or list of str
        Geohash cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "w3gvk1td8"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid Geohash cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the Geohash cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> geohash2geojson("w3gvk1td8")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> geohash2geojson(["w3gvk1td8", "w3gvk1td9"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(geohash_ids, str):
        geohash_ids = [geohash_ids]
    geohash_features = []
    for geohash_id in geohash_ids:
        try:
            cell_polygon = geohash2geo(geohash_id)
            resolution = len(geohash_id)
            geohash_feature = graticule_dggs_to_feature(
                "geohash", geohash_id, resolution, cell_polygon
            )
            geohash_features.append(geohash_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": geohash_features}

geohash2geojson_cli()

Command-line interface for geohash2geojson supporting multiple Geohash cell IDs.

Source code in vgrid/conversion/dggs2geo/geohash2geo.py

def geohash2geojson_cli():
    """
    Command-line interface for geohash2geojson supporting multiple Geohash cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert Geohash cell ID(s) to GeoJSON"
    )
    parser.add_argument(
        "geohash",
        nargs="+",
        help="Input Geohash cell ID(s), e.g., geohash2geojson w3gvk1td8 ...",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(geohash2geojson(args.geohash))
    print(geojson_data)

georef2geo_cli()

Command-line interface for georef2geo supporting multiple GEOREF codes.

Source code in vgrid/conversion/dggs2geo/georef2geo.py

def georef2geo_cli():
    """
    Command-line interface for georef2geo supporting multiple GEOREF codes.
    """
    parser = argparse.ArgumentParser(
        description="Convert GEOREF code(s) to Shapely Polygons"
    )
    parser.add_argument(
        "georef",
        nargs="+",
        help="Input GEOREF code(s), e.g., georef2geo VGBL42404651 ...",
    )
    args = parser.parse_args()
    polys = georef2geo(args.georef)
    return polys

georef2geojson(georef_ids)

Convert GEOREF codes to GeoJSON FeatureCollection.

Accepts a single georef_id (string) or a list of georef_ids. For each valid GEOREF code, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

georef_ids : str or list of str GEOREF code(s) to convert. Can be a single string or a list of strings. Example format: "VGBL42404651"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid GEOREF cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the GEOREF code, resolution level, and cell metadata

Examples

georef2geojson("VGBL42404651")

georef2geojson(["VGBL42404651", "VGBL42404652"])

Source code in vgrid/conversion/dggs2geo/georef2geo.py

def georef2geojson(georef_ids):
    """
    Convert GEOREF codes to GeoJSON FeatureCollection.

    Accepts a single georef_id (string) or a list of georef_ids. For each valid GEOREF code,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    georef_ids : str or list of str
        GEOREF code(s) to convert. Can be a single string or a list of strings.
        Example format: "VGBL42404651"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid GEOREF cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the GEOREF code, resolution level, and cell metadata

    Examples
    --------
    >>> georef2geojson("VGBL42404651")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> georef2geojson(["VGBL42404651", "VGBL42404652"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(georef_ids, str):
        georef_ids = [georef_ids]
    georef_features = []
    for georef_id in georef_ids:
        try:
            _, _, min_lat, min_lon, max_lat, max_lon, resolution = georef.georefcell(
                georef_id
            )
            cell_polygon = Polygon(
                [
                    [min_lon, min_lat],
                    [max_lon, min_lat],
                    [max_lon, max_lat],
                    [min_lon, max_lat],
                    [min_lon, min_lat],
                ]
            )
            georef_feature = graticule_dggs_to_feature(
                "georef", georef_id, resolution, cell_polygon
            )
            georef_features.append(georef_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": georef_features}

georef2geojson_cli()

Command-line interface for georef2geojson supporting multiple GEOREF codes.

Source code in vgrid/conversion/dggs2geo/georef2geo.py

def georef2geojson_cli():
    """
    Command-line interface for georef2geojson supporting multiple GEOREF codes.
    """
    parser = argparse.ArgumentParser(description="Convert GEOREF code(s) to GeoJSON")
    parser.add_argument(
        "georef",
        nargs="+",
        help="Input GEOREF code(s), e.g., georef2geojson VGBL42404651 ...",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(georef2geojson(args.georef))
    print(geojson_data)

h32geo_cli()

Command-line interface for h32geo supporting multiple H3 cell IDs.

Source code in vgrid/conversion/dggs2geo/h32geo.py

def h32geo_cli():
    """
    Command-line interface for h32geo supporting multiple H3 cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert H3 cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "h3",
        nargs="+",
        help="Input H3 cell ID(s), e.g., h32geo 8e65b56628e0d07 8e65b56628e6adf",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    polys = h32geo(args.h3, fix_antimeridian=args.fix_antimeridian)
    return polys

h32geojson(h3_ids, fix_antimeridian=None)

Convert H3 cell IDs to GeoJSON FeatureCollection.

Accepts a single h3_id (string) or a list of h3_ids. For each valid H3 cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

h3_ids : str or list of str H3 cell ID(s) to convert. Can be a single string or a list of strings. Example format: "8e65b56628e0d07" fix_antimeridian : str, optional When 'shift' or 'shift_balanced', apply balanced antimeridian shifting. When 'shift_west', apply westward antimeridian shifting. When 'shift_east', apply eastward antimeridian shifting. When 'split', apply antimeridian splitting to the resulting polygons. When None or not provided, do not apply any antimeridian fixing. Defaults to None.

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid H3 cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the H3 cell ID, resolution level, and cell metadata

Examples

h32geojson("8e65b56628e0d07")

h32geojson(["8e65b56628e0d07", "8e65b56628e6adf"])

Source code in vgrid/conversion/dggs2geo/h32geo.py

def h32geojson(h3_ids, fix_antimeridian=None):
    """
    Convert H3 cell IDs to GeoJSON FeatureCollection.

    Accepts a single h3_id (string) or a list of h3_ids. For each valid H3 cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    h3_ids : str or list of str
        H3 cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "8e65b56628e0d07"
    fix_antimeridian : str, optional
        When 'shift' or 'shift_balanced', apply balanced antimeridian shifting.
        When 'shift_west', apply westward antimeridian shifting.
        When 'shift_east', apply eastward antimeridian shifting.
        When 'split', apply antimeridian splitting to the resulting polygons.
        When None or not provided, do not apply any antimeridian fixing.
        Defaults to None.

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid H3 cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the H3 cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> h32geojson("8e65b56628e0d07")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> h32geojson(["8e65b56628e0d07", "8e65b56628e6adf"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(h3_ids, str):
        h3_ids = [h3_ids]
    h3_features = []
    for h3_id in h3_ids:
        try:
            cell_polygon = h32geo(h3_id, fix_antimeridian=fix_antimeridian)
            resolution = h3_id
            num_edges = 6
            if h3.is_pentagon(h3_id):
                num_edges = 5
            h3_feature = geodesic_dggs_to_feature(
                "h3", h3_id, resolution, cell_polygon, num_edges
            )
            h3_features.append(h3_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": h3_features}

h32geojson_cli()

Command-line interface for h32geojson supporting multiple H3 cell IDs.

Source code in vgrid/conversion/dggs2geo/h32geo.py

def h32geojson_cli():
    """
    Command-line interface for h32geojson supporting multiple H3 cell IDs.
    """
    parser = argparse.ArgumentParser(description="Convert H3 cell ID(s) to GeoJSON")
    parser.add_argument(
        "h3",
        nargs="+",
        help="Input H3 cell ID(s), e.g., h32geojson 8e65b56628e0d07 8e65b56628e6adf",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(
        h32geojson(args.h3, fix_antimeridian=args.fix_antimeridian)
    )
    print(geojson_data)

isea3h2geo_cli()

Command-line interface for isea3h2geo supporting multiple ISEA3H cell IDs.

Source code in vgrid/conversion/dggs2geo/isea3h2geo.py

def isea3h2geo_cli():
    """
    Command-line interface for isea3h2geo supporting multiple ISEA3H cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert ISEA3H cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "isea3h",
        nargs="+",
        help="Input ISEA3H cell ID(s), e.g., isea3h2geo 1327916769,-55086 ...",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    if platform.system() == "Windows":
        polys = isea3h2geo(args.isea3h, fix_antimeridian=args.fix_antimeridian)
        return polys
    else:
        print("ISEA3H is only supported on Windows systems")

isea3h2geojson(isea3h_ids, fix_antimeridian=None)

Convert ISEA3H cell IDs to GeoJSON FeatureCollection.

Accepts a single isea3h_id (string) or a list of isea3h_ids. For each valid ISEA3H cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

isea3h_ids : str or list of str ISEA3H cell ID(s) to convert. Can be a single string or a list of strings. Example format: "1327916769,-55086" fix_antimeridian : str, optional Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid ISEA3H cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the ISEA3H cell ID, resolution level, center coordinates, edge length, and cell area

Examples

isea3h2geojson("1327916769,-55086")

isea3h2geojson(["1327916769,-55086", "1327916770,-55087"])

Source code in vgrid/conversion/dggs2geo/isea3h2geo.py

def isea3h2geojson(isea3h_ids, fix_antimeridian=None):
    """
    Convert ISEA3H cell IDs to GeoJSON FeatureCollection.

    Accepts a single isea3h_id (string) or a list of isea3h_ids. For each valid ISEA3H cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    isea3h_ids : str or list of str
        ISEA3H cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "1327916769,-55086"
    fix_antimeridian : str, optional
        Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid ISEA3H cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the ISEA3H cell ID, resolution level, center coordinates, edge length, and cell area

    Examples
    --------
    >>> isea3h2geojson("1327916769,-55086")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> isea3h2geojson(["1327916769,-55086", "1327916770,-55087"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(isea3h_ids, str):
        isea3h_ids = [isea3h_ids]
    features = []
    for isea3h_id in isea3h_ids:
        try:
            isea3h_cell = DggsCell(isea3h_id)
            cell_polygon = isea3h2geo(isea3h_id)
            if fix_antimeridian:
                cell_polygon = fix_polygon(cell_polygon)
            cell_centroid = cell_polygon.centroid
            center_lat = cell_centroid.y
            center_lon = cell_centroid.x
            cell_area = abs(geod.geometry_area_perimeter(cell_polygon)[0])
            cell_perimeter = abs(geod.geometry_area_perimeter(cell_polygon)[1])
            isea3h2point = isea3h_dggs.convert_dggs_cell_to_point(isea3h_cell)
            cell_accuracy = isea3h2point._accuracy
            avg_edge_len = cell_perimeter / 6
            cell_resolution = ISEA3H_ACCURACY_RES_DICT.get(cell_accuracy)
            if cell_resolution == 0:
                avg_edge_len = cell_perimeter / 3
            if cell_accuracy == 0.0:
                if round(avg_edge_len, 2) == 0.06:
                    cell_resolution = 33
                elif round(avg_edge_len, 2) == 0.03:
                    cell_resolution = 34
                elif round(avg_edge_len, 2) == 0.02:
                    cell_resolution = 35
                elif round(avg_edge_len, 2) == 0.01:
                    cell_resolution = 36
                elif round(avg_edge_len, 3) == 0.007:
                    cell_resolution = 37
                elif round(avg_edge_len, 3) == 0.004:
                    cell_resolution = 38
                elif round(avg_edge_len, 3) == 0.002:
                    cell_resolution = 39
                elif round(avg_edge_len, 3) <= 0.001:
                    cell_resolution = 40
            feature = {
                "type": "Feature",
                "geometry": mapping(cell_polygon),
                "properties": {
                    "isea3h": isea3h_id,
                    "resolution": cell_resolution,
                    "center_lat": center_lat,
                    "center_lon": center_lon,
                    "avg_edge_len": round(avg_edge_len, 3),
                    "cell_area": cell_area,
                },
            }
            features.append(feature)
        except Exception:
            continue
    feature_collection = {"type": "FeatureCollection", "features": features}
    return feature_collection

isea3h2geojson_cli()

Command-line interface for isea3h2geojson supporting multiple ISEA3H cell IDs.

Source code in vgrid/conversion/dggs2geo/isea3h2geo.py

def isea3h2geojson_cli():
    """
    Command-line interface for isea3h2geojson supporting multiple ISEA3H cell IDs.
    """
    parser = argparse.ArgumentParser(description="Convert ISEA3H ID(s) to GeoJSON")
    parser.add_argument(
        "isea3h",
        nargs="+",
        help="Input ISEA3H cell ID(s), e.g., isea3h2geojson 1327916769,-55086 ...",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    if platform.system() == "Windows":
        geojson_data = json.dumps(
            isea3h2geojson(args.isea3h, fix_antimeridian=args.fix_antimeridian)
        )
        print(geojson_data)
    else:
        print("ISEA3H is only supported on Windows systems")

isea4t2geo_cli()

Command-line interface for isea4t2geo supporting multiple ISEA4T cell IDs.

Source code in vgrid/conversion/dggs2geo/isea4t2geo.py

def isea4t2geo_cli():
    """
    Command-line interface for isea4t2geo supporting multiple ISEA4T cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert ISEA4T cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "isea4t",
        nargs="+",
        help="Input isea4t code(s), e.g., isea4t2geo 131023133313201333311333 ...",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    if platform.system() == "Windows":
        polys = isea4t2geo(args.isea4t, fix_antimeridian=args.fix_antimeridian)
        return polys
    else:
        print("ISEA4T is only supported on Windows systems")

isea4t2geojson(isea4t_ids, fix_antimeridian=None)

Convert ISEA4T cell IDs to GeoJSON FeatureCollection.

Accepts a single isea4t_id (string) or a list of isea4t_ids. For each valid ISEA4T cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

isea4t_ids : str or list of str ISEA4T cell ID(s) to convert. Can be a single string or a list of strings. Example format: "131023133313201333311333" fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid ISEA4T cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the ISEA4T cell ID, resolution level, and cell metadata

Examples

isea4t2geojson("131023133313201333311333")

isea4t2geojson(["131023133313201333311333", "131023133313201333311334"])

Source code in vgrid/conversion/dggs2geo/isea4t2geo.py

def isea4t2geojson(isea4t_ids, fix_antimeridian=None):
    """
    Convert ISEA4T cell IDs to GeoJSON FeatureCollection.

    Accepts a single isea4t_id (string) or a list of isea4t_ids. For each valid ISEA4T cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    isea4t_ids : str or list of str
        ISEA4T cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "131023133313201333311333"
    fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid ISEA4T cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the ISEA4T cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> isea4t2geojson("131023133313201333311333")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> isea4t2geojson(["131023133313201333311333", "131023133313201333311334"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(isea4t_ids, str):
        isea4t_ids = [isea4t_ids]
    isea4t_features = []
    for isea4t_id in isea4t_ids:
        try:
            cell_polygon = isea4t2geo(isea4t_id, fix_antimeridian=fix_antimeridian)
            resolution = len(isea4t_id) - 2
            num_edges = 3
            isea4t_feature = geodesic_dggs_to_feature(
                "isea4t", isea4t_id, resolution, cell_polygon, num_edges
            )
            isea4t_features.append(isea4t_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": isea4t_features}

isea4t2geojson_cli()

Command-line interface for isea4t2geojson supporting multiple ISEA4T cell IDs.

Source code in vgrid/conversion/dggs2geo/isea4t2geo.py

def isea4t2geojson_cli():
    """
    Command-line interface for isea4t2geojson supporting multiple ISEA4T cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert Open-Eaggr ISEA4T cell ID(s) to GeoJSON"
    )
    parser.add_argument(
        "isea4t",
        nargs="+",
        help="Input isea4t code(s), e.g., isea4t2geojson 131023133313201333311333 ...",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    if platform.system() == "Windows":
        geojson_data = json.dumps(
            isea4t2geojson(args.isea4t, fix_antimeridian=args.fix_antimeridian)
        )
        print(geojson_data)
    else:
        print("ISEA4T is only supported on Windows systems")

maidenhead2geo_cli()

Command-line interface for maidenhead2geo supporting multiple Maidenhead cell IDs.

Source code in vgrid/conversion/dggs2geo/maidenhead2geo.py

def maidenhead2geo_cli():
    """
    Command-line interface for maidenhead2geo supporting multiple Maidenhead cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert Maidenhead cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "maidenhead",
        nargs="+",
        help="Input Maidenhead cell ID(s), e.g., maidenhead2geo OK3046.",
    )
    args = parser.parse_args()
    polys = maidenhead2geo(args.maidenhead)
    return polys

maidenhead2geojson(maidenhead_ids)

Convert Maidenhead cell IDs to GeoJSON FeatureCollection.

Accepts a single maidenhead_id (string) or a list of maidenhead_ids. For each valid Maidenhead cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

maidenhead_ids : str or list of str Maidenhead cell ID(s) to convert. Can be a single string or a list of strings. Example format: "OK3046."

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid Maidenhead cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the Maidenhead cell ID, resolution level, and cell metadata

Examples

maidenhead2geojson("OK3046.")

maidenhead2geojson(["OK3046.", "OK3047."])

Source code in vgrid/conversion/dggs2geo/maidenhead2geo.py

def maidenhead2geojson(maidenhead_ids):
    """
    Convert Maidenhead cell IDs to GeoJSON FeatureCollection.

    Accepts a single maidenhead_id (string) or a list of maidenhead_ids. For each valid Maidenhead cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    maidenhead_ids : str or list of str
        Maidenhead cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "OK3046."

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid Maidenhead cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the Maidenhead cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> maidenhead2geojson("OK3046.")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> maidenhead2geojson(["OK3046.", "OK3047."])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(maidenhead_ids, str):
        maidenhead_ids = [maidenhead_ids]
    maidenhead_features = []
    for maidenhead_id in maidenhead_ids:
        try:
            cell_polygon = maidenhead2geo(maidenhead_id)
            resolution = int(len(maidenhead_id) / 2)
            maidenhead_feature = graticule_dggs_to_feature(
                "maidenhead", maidenhead_id, resolution, cell_polygon
            )
            maidenhead_features.append(maidenhead_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": maidenhead_features}

maidenhead2geojson_cli()

Command-line interface for maidenhead2geojson supporting multiple Maidenhead cell IDs.

Source code in vgrid/conversion/dggs2geo/maidenhead2geo.py

def maidenhead2geojson_cli():
    """
    Command-line interface for maidenhead2geojson supporting multiple Maidenhead cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert Maidenhead cell ID(s) to GeoJSON"
    )
    parser.add_argument(
        "maidenhead",
        nargs="+",
        help="Input Maidenhead cell ID(s), e.g., maidenhead2geojson OK3046.",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(maidenhead2geojson(args.maidenhead))
    print(geojson_data)

mgrs2geo_cli()

Command-line interface for mgrs2geo supporting multiple MGRS cell IDs.

Source code in vgrid/conversion/dggs2geo/mgrs2geo.py

def mgrs2geo_cli():
    """
    Command-line interface for mgrs2geo supporting multiple MGRS cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert MGRS cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "mgrs",
        nargs="+",
        help="Input MGRS cell ID(s), e.g., mgrs2geo 48PXS866916 ...",
    )
    args = parser.parse_args()
    polys = mgrs2geo(args.mgrs)
    return polys

mgrs2geojson(mgrs_ids)

Convert MGRS cell IDs to GeoJSON FeatureCollection.

Accepts a single mgrs_id (string) or a list of mgrs_ids. For each valid MGRS cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

mgrs_ids : str or list of str MGRS cell ID(s) to convert. Can be a single string or a list of strings. Example format: "48PXS866916"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid MGRS cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the MGRS cell ID, resolution level, and cell metadata

Examples

mgrs2geojson("48PXS866916")

mgrs2geojson(["48PXS866916", "48PXS866917"])

Source code in vgrid/conversion/dggs2geo/mgrs2geo.py

def mgrs2geojson(mgrs_ids):
    """
    Convert MGRS cell IDs to GeoJSON FeatureCollection.

    Accepts a single mgrs_id (string) or a list of mgrs_ids. For each valid MGRS cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    mgrs_ids : str or list of str
        MGRS cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "48PXS866916"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid MGRS cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the MGRS cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> mgrs2geojson("48PXS866916")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> mgrs2geojson(["48PXS866916", "48PXS866917"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(mgrs_ids, str):
        mgrs_ids = [mgrs_ids]
    mgrs_features = []
    for mgrs_id in mgrs_ids:
        try:
            min_lat, min_lon, max_lat, max_lon, resolution = mgrs.mgrscell(mgrs_id)
            cell_polygon = Polygon(
                [
                    (min_lon, min_lat),
                    (max_lon, min_lat),
                    (max_lon, max_lat),
                    (min_lon, max_lat),
                    (min_lon, min_lat),
                ]
            )
            mgrs_feature = graticule_dggs_to_feature(
                "mgrs", mgrs_id, resolution, cell_polygon
            )
            try:
                gzd_json_path = os.path.join(
                    os.path.dirname(__file__), "../generator/gzd.geojson"
                )
                with open(gzd_json_path, "r", encoding="utf-8") as f:
                    gzd_data = json.load(f)
                gzd_features = gzd_data["features"]
                gzd_feature = [
                    feature
                    for feature in gzd_features
                    if feature["properties"].get("gzd") == mgrs_id[:3]
                ][0]
                gzd_geom = shape(gzd_feature["geometry"])
                if mgrs_id[2] not in {"A", "B", "Y", "Z"}:
                    if cell_polygon.intersects(gzd_geom) and not gzd_geom.contains(
                        cell_polygon
                    ):
                        intersected_polygon = cell_polygon.intersection(gzd_geom)
                        if intersected_polygon:
                            mgrs_feature = graticule_dggs_to_feature(
                                "mgrs", mgrs_id, resolution, intersected_polygon
                            )
            except Exception:
                pass
            mgrs_features.append(mgrs_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": mgrs_features}

mgrs2geojson_cli()

Command-line interface for mgrs2geojson supporting multiple MGRS cell IDs.

Source code in vgrid/conversion/dggs2geo/mgrs2geo.py

def mgrs2geojson_cli():
    """
    Command-line interface for mgrs2geojson supporting multiple MGRS cell IDs.
    """
    parser = argparse.ArgumentParser(description="Convert MGRS cell ID(s) to GeoJSON")
    parser.add_argument(
        "mgrs",
        nargs="+",
        help="Input MGRS cell ID(s), e.g., mgrs2geojson 48PXS866916 ...",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(mgrs2geojson(args.mgrs))
    print(geojson_data)

olc2geo_cli()

Command-line interface for olc2geo supporting multiple OLC codes.

Source code in vgrid/conversion/dggs2geo/olc2geo.py

def olc2geo_cli():
    """
    Command-line interface for olc2geo supporting multiple OLC codes.
    """
    parser = argparse.ArgumentParser(
        description="Convert OLC/Google Plus Codes to Shapely Polygons"
    )
    parser.add_argument(
        "olc",
        nargs="+",
        help="Input OLC(s), e.g., olc2geo 7P28QPG4+4P7 7P28QPG4+4P8",
    )
    args = parser.parse_args()
    polys = olc2geo(args.olc)
    return polys

olc2geojson(olc_ids)

Convert OLC (Open Location Code) cell IDs to GeoJSON FeatureCollection.

Accepts a single olc_id (string) or a list of olc_ids. For each valid OLC cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

olc_ids : str or list of str OLC cell ID(s) to convert. Can be a single string or a list of strings. Example format: "7P28QPG4+4P7"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid OLC cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the OLC cell ID, resolution level, and cell metadata

Examples

olc2geojson("7P28QPG4+4P7")

olc2geojson(["7P28QPG4+4P7", "7P28QPG4+4P8"])

Source code in vgrid/conversion/dggs2geo/olc2geo.py

def olc2geojson(olc_ids):
    """
    Convert OLC (Open Location Code) cell IDs to GeoJSON FeatureCollection.

    Accepts a single olc_id (string) or a list of olc_ids. For each valid OLC cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    olc_ids : str or list of str
        OLC cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "7P28QPG4+4P7"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid OLC cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the OLC cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> olc2geojson("7P28QPG4+4P7")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> olc2geojson(["7P28QPG4+4P7", "7P28QPG4+4P8"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(olc_ids, str):
        olc_ids = [olc_ids]
    olc_features = []
    for olc_id in olc_ids:
        try:
            cell_polygon = olc2geo(olc_id)
            coord = olc.decode(olc_id)
            resolution = coord.codeLength
            olc_feature = graticule_dggs_to_feature(
                "olc", olc_id, resolution, cell_polygon
            )
            olc_features.append(olc_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": olc_features}

olc2geojson_cli()

Command-line interface for olc2geojson supporting multiple OLC codes.

Source code in vgrid/conversion/dggs2geo/olc2geo.py

def olc2geojson_cli():
    """
    Command-line interface for olc2geojson supporting multiple OLC codes.
    """
    parser = argparse.ArgumentParser(
        description="Convert OLC/ Google Plus Codes to GeoJSON"
    )
    parser.add_argument(
        "olc",
        nargs="+",
        help="Input OLC(s), e.g., olc2geojson 7P28QPG4+4P7 7P28QPG4+4P8",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(olc2geojson(args.olc))
    print(geojson_data)

qtm2geo_cli()

Command-line interface for qtm2geo supporting multiple QTM cell IDs.

Source code in vgrid/conversion/dggs2geo/qtm2geo.py

def qtm2geo_cli():
    """
    Command-line interface for qtm2geo supporting multiple QTM cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert QTM cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "qtm",
        nargs="+",
        help="Input QTM cell ID(s), e.g., qtm2geo 42012321 42012322",
    )
    args = parser.parse_args()
    polys = qtm2geo(args.qtm)
    return polys

qtm2geojson(qtm_ids)

Convert QTM cell IDs to GeoJSON FeatureCollection.

Accepts a single qtm_id (string) or a list of qtm_ids. For each valid QTM cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

qtm_ids : str or list of str QTM cell ID(s) to convert. Can be a single string or a list of strings. Example format: "42012321"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid QTM cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the QTM cell ID, resolution level, and cell metadata

Examples

qtm2geojson("42012321")

qtm2geojson(["42012321", "42012322"])

Source code in vgrid/conversion/dggs2geo/qtm2geo.py

def qtm2geojson(qtm_ids):
    """
    Convert QTM cell IDs to GeoJSON FeatureCollection.

    Accepts a single qtm_id (string) or a list of qtm_ids. For each valid QTM cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    qtm_ids : str or list of str
        QTM cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "42012321"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid QTM cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the QTM cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> qtm2geojson("42012321")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> qtm2geojson(["42012321", "42012322"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(qtm_ids, str):
        qtm_ids = [qtm_ids]
    qtm_features = []
    for qtm_id in qtm_ids:
        try:
            cell_polygon = qtm2geo(qtm_id)
            resolution = len(qtm_id)
            num_edges = 3
            qtm_feature = geodesic_dggs_to_feature(
                "qtm", qtm_id, resolution, cell_polygon, num_edges
            )
            qtm_features.append(qtm_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": qtm_features}

qtm2geojson_cli()

Command-line interface for qtm2geojson supporting multiple QTM cell IDs.

Source code in vgrid/conversion/dggs2geo/qtm2geo.py

def qtm2geojson_cli():
    """
    Command-line interface for qtm2geojson supporting multiple QTM cell IDs.
    """
    parser = argparse.ArgumentParser(description="Convert QTM cell ID(s) to GeoJSON")
    parser.add_argument(
        "qtm",
        nargs="+",
        help="Input QTM cell ID(s), e.g., qtm2geojson 42012321 42012322",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(qtm2geojson(args.qtm))
    print(geojson_data)

quadkey2geo_cli()

Command-line interface for quadkey2geo supporting multiple Quadkeys.

Source code in vgrid/conversion/dggs2geo/quadkey2geo.py

def quadkey2geo_cli():
    """
    Command-line interface for quadkey2geo supporting multiple Quadkeys.
    """
    parser = argparse.ArgumentParser(
        description="Convert Quadkey(s) to Shapely Polygons"
    )
    parser.add_argument(
        "quadkey", nargs="+", help="Input Quadkey(s), e.g. 13223011131020220011133 ..."
    )
    args = parser.parse_args()
    polys = quadkey2geo(args.quadkey)
    return polys

quadkey2geojson(quadkey_ids)

Convert Quadkey cell IDs to GeoJSON FeatureCollection.

Accepts a single quadkey_id (string) or a list of quadkey_ids. For each valid Quadkey cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

quadkey_ids : str or list of str Quadkey cell ID(s) to convert. Can be a single string or a list of strings. Example format: "13223011131020220011133"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid Quadkey cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the Quadkey cell ID, resolution level, and cell metadata

Examples

quadkey2geojson("13223011131020220011133")

quadkey2geojson(["13223011131020220011133", "13223011131020220011134"])

Source code in vgrid/conversion/dggs2geo/quadkey2geo.py

def quadkey2geojson(quadkey_ids):
    """
    Convert Quadkey cell IDs to GeoJSON FeatureCollection.

    Accepts a single quadkey_id (string) or a list of quadkey_ids. For each valid Quadkey cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    quadkey_ids : str or list of str
        Quadkey cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "13223011131020220011133"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid Quadkey cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the Quadkey cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> quadkey2geojson("13223011131020220011133")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> quadkey2geojson(["13223011131020220011133", "13223011131020220011134"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(quadkey_ids, str):
        quadkey_ids = [quadkey_ids]
    quadkey_features = []
    for quadkey_id in quadkey_ids:
        try:
            tile = mercantile.quadkey_to_tile(quadkey_id)
            z = tile.z
            x = tile.x
            y = tile.y
            bounds = mercantile.bounds(x, y, z)
            if bounds:
                min_lat, min_lon = bounds.south, bounds.west
                max_lat, max_lon = bounds.north, bounds.east
                cell_polygon = Polygon(
                    [
                        [min_lon, min_lat],
                        [max_lon, min_lat],
                        [max_lon, max_lat],
                        [min_lon, max_lat],
                        [min_lon, min_lat],
                    ]
                )
                resolution = z
                quadkey_feature = graticule_dggs_to_feature(
                    "quadkey", quadkey_id, resolution, cell_polygon
                )
                quadkey_features.append(quadkey_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": quadkey_features}

quadkey2geojson_cli()

Command-line interface for quadkey2geojson supporting multiple Quadkeys.

Source code in vgrid/conversion/dggs2geo/quadkey2geo.py

def quadkey2geojson_cli():
    """
    Command-line interface for quadkey2geojson supporting multiple Quadkeys.
    """
    parser = argparse.ArgumentParser(description="Convert Quadkey(s) to GeoJSON")
    parser.add_argument(
        "quadkey", nargs="+", help="Input Quadkey(s), e.g. 13223011131020220011133 ..."
    )
    args = parser.parse_args()
    geojson_data = json.dumps(quadkey2geojson(args.quadkey))
    print(geojson_data)

rhealpix2geo_cli()

Command-line interface for converting RHEALPix cell IDs to Shapely Polygons.

This function provides a command-line interface that accepts multiple RHEALPix cell IDs as command-line arguments and returns the corresponding Shapely Polygon objects.

Returns:

Name	Type	Description
list		A list of Shapely Polygon objects representing the converted cells.

Usage

rhealpix2geo R31260335553825 R31260335553826

Note

This function is designed to be called from the command line and will parse arguments using argparse. Invalid cell IDs are silently skipped.

Source code in vgrid/conversion/dggs2geo/rhealpix2geo.py

def rhealpix2geo_cli():
    """
    Command-line interface for converting RHEALPix cell IDs to Shapely Polygons.

    This function provides a command-line interface that accepts multiple RHEALPix
    cell IDs as command-line arguments and returns the corresponding Shapely
    Polygon objects.

    Returns:
        list: A list of Shapely Polygon objects representing the converted cells.

    Usage:
        rhealpix2geo R31260335553825 R31260335553826

    Note:
        This function is designed to be called from the command line and will
        parse arguments using argparse. Invalid cell IDs are silently skipped.
    """
    parser = argparse.ArgumentParser(
        description="Convert Rhealpix cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "rhealpix",
        nargs="+",
        help="Input Rhealpix cell ID(s), e.g., rhealpix2geo R31260335553825 R31260335553826",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    polys = rhealpix2geo(args.rhealpix, fix_antimeridian=args.fix_antimeridian)
    return polys

rhealpix2geojson(rhealpix_ids, fix_antimeridian=None)

Convert RHEALPix cell IDs to GeoJSON FeatureCollection.

Accepts a single rhealpix_id (string) or a list of rhealpix_ids. For each valid RHEALPix cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

rhealpix_ids : str or list of str RHEALPix cell ID(s) to convert. Can be a single string or a list of strings. Each ID should be a string starting with 'R' followed by numeric digits. Example format: "R31260335553825" fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none When True, apply antimeridian fixing to the resulting polygons. Defaults to False when None or omitted.

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid RHEALPix cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the RHEALPix cell ID, resolution level, and cell metadata

Examples

rhealpix2geojson("R31260335553825")

rhealpix2geojson(["R31260335553825", "R31260335553826"])

Source code in vgrid/conversion/dggs2geo/rhealpix2geo.py

def rhealpix2geojson(rhealpix_ids, fix_antimeridian=None):
    """
    Convert RHEALPix cell IDs to GeoJSON FeatureCollection.

    Accepts a single rhealpix_id (string) or a list of rhealpix_ids. For each valid RHEALPix cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    rhealpix_ids : str or list of str
        RHEALPix cell ID(s) to convert. Can be a single string or a list of strings.
        Each ID should be a string starting with 'R' followed by numeric digits.
        Example format: "R31260335553825"
    fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none
        When True, apply antimeridian fixing to the resulting polygons.
        Defaults to False when None or omitted.

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid RHEALPix cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the RHEALPix cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> rhealpix2geojson("R31260335553825")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> rhealpix2geojson(["R31260335553825", "R31260335553826"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(rhealpix_ids, str):
        rhealpix_ids = [rhealpix_ids]
    rhealpix_features = []
    for rhealpix_id in rhealpix_ids:
        try:
            rhealpix_uids = (rhealpix_id[0],) + tuple(map(int, rhealpix_id[1:]))
            rhealpix_cell = rhealpix_dggs.cell(rhealpix_uids)
            resolution = rhealpix_cell.resolution
            cell_polygon = rhealpix_cell_to_polygon(rhealpix_cell)
            if fix_antimeridian == "shift" or fix_antimeridian == "shift_balanced":
                cell_polygon = shift_balanced(
                    cell_polygon, threshold_west=-128, threshold_east=160
                )
            elif fix_antimeridian == "shift_west":
                cell_polygon = shift_west(cell_polygon, threshold=-128)
            elif fix_antimeridian == "shift_east":
                cell_polygon = shift_east(cell_polygon, threshold=160)
            elif fix_antimeridian == "split":
                cell_polygon = fix_polygon(cell_polygon)
            num_edges = 4
            if rhealpix_cell.ellipsoidal_shape() == "dart":
                num_edges = 3
            rhealpix_feature = geodesic_dggs_to_feature(
                "rhealpix", rhealpix_id, resolution, cell_polygon, num_edges
            )
            rhealpix_features.append(rhealpix_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": rhealpix_features}

rhealpix2geojson_cli()

Command-line interface for converting RHEALPix cell IDs to GeoJSON.

This function provides a command-line interface that accepts multiple RHEALPix cell IDs as command-line arguments and outputs the corresponding GeoJSON FeatureCollection as a JSON string to stdout.

Usage

rhealpix2geojson R31260335553825 R31260335553826

Output

Prints a JSON string representing a GeoJSON FeatureCollection to stdout.

Example

$ python -m vgrid.conversion.dggs2geo.rhealpix2geo R31260335553825

Note

This function is designed to be called from the command line and will parse arguments using argparse. The GeoJSON output is formatted as a JSON string printed to stdout. Invalid cell IDs are silently skipped.

Source code in vgrid/conversion/dggs2geo/rhealpix2geo.py

def rhealpix2geojson_cli():
    """
    Command-line interface for converting RHEALPix cell IDs to GeoJSON.

    This function provides a command-line interface that accepts multiple RHEALPix
    cell IDs as command-line arguments and outputs the corresponding GeoJSON
    FeatureCollection as a JSON string to stdout.

    Usage:
        rhealpix2geojson R31260335553825 R31260335553826

    Output:
        Prints a JSON string representing a GeoJSON FeatureCollection to stdout.

    Example:
        $ python -m vgrid.conversion.dggs2geo.rhealpix2geo R31260335553825
        {"type": "FeatureCollection", "features": [...]}

    Note:
        This function is designed to be called from the command line and will
        parse arguments using argparse. The GeoJSON output is formatted as a
        JSON string printed to stdout. Invalid cell IDs are silently skipped.
    """
    parser = argparse.ArgumentParser(
        description="Convert Rhealpix cell ID(s) to GeoJSON"
    )
    parser.add_argument(
        "rhealpix",
        nargs="+",
        help="Input Rhealpix cell ID(s), e.g., rhealpix2geojson R31260335553825 R31260335553826",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(
        rhealpix2geojson(args.rhealpix, fix_antimeridian=args.fix_antimeridian)
    )
    print(geojson_data)

s22geo_cli()

Command-line interface for s22geo supporting multiple S2 cell tokens.

Source code in vgrid/conversion/dggs2geo/s22geo.py

def s22geo_cli():
    """
    Command-line interface for s22geo supporting multiple S2 cell tokens.
    """
    parser = argparse.ArgumentParser(
        description="Convert S2 cell token(s) to Shapely Polygons"
    )
    parser.add_argument(
        "s2",
        nargs="+",
        help="Input S2 cell token(s), e.g., s22geo 31752f45cc94 31752f45cc95",
    )
    args = parser.parse_args()
    polys = s22geo(args.s2)
    return polys

s22geojson(s2_tokens, fix_antimeridian=None)

Convert S2 cell tokens to GeoJSON FeatureCollection.

Accepts a single s2_token (string) or a list of s2_tokens. For each valid S2 cell token, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

s2_tokens : str or list of str S2 cell token(s) to convert. Can be a single string or a list of strings. Example format: "31752f45cc94" fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none Returns

---

dict A GeoJSON FeatureCollection containing polygon features for each valid S2 cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the S2 cell token, resolution level, and cell metadata

Examples

s22geojson("31752f45cc94")

s22geojson(["31752f45cc94", "31752f45cc95"])

Source code in vgrid/conversion/dggs2geo/s22geo.py

def s22geojson(s2_tokens, fix_antimeridian=None):
    """
    Convert S2 cell tokens to GeoJSON FeatureCollection.

    Accepts a single s2_token (string) or a list of s2_tokens. For each valid S2 cell token,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    s2_tokens : str or list of str
        S2 cell token(s) to convert. Can be a single string or a list of strings.
        Example format: "31752f45cc94"
    fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none
    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid S2 cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the S2 cell token, resolution level, and cell metadata

    Examples
    --------
    >>> s22geojson("31752f45cc94")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> s22geojson(["31752f45cc94", "31752f45cc95"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(s2_tokens, str):
        s2_tokens = [s2_tokens]
    s2_features = []
    for s2_token in s2_tokens:
        try:
            cell_id = s2.CellId.from_token(s2_token)
            cell_polygon = s22geo(s2_token, fix_antimeridian=fix_antimeridian)
            resolution = cell_id.level()
            num_edges = 4
            s2_feature = geodesic_dggs_to_feature(
                "s2", s2_token, resolution, cell_polygon, num_edges
            )
            s2_features.append(s2_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": s2_features}

s22geojson_cli()

Command-line interface for s22geojson supporting multiple S2 cell tokens.

Source code in vgrid/conversion/dggs2geo/s22geo.py

def s22geojson_cli():
    """
    Command-line interface for s22geojson supporting multiple S2 cell tokens.
    """
    parser = argparse.ArgumentParser(description="Convert S2 cell token(s) to GeoJSON")
    parser.add_argument(
        "s2",
        nargs="+",
        help="Input S2 cell token(s), e.g., s22geojson 31752f45cc94 31752f45cc95",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    fix_antimeridian = args.fix_antimeridian
    geojson_data = json.dumps(s22geojson(args.s2, fix_antimeridian=fix_antimeridian))
    print(geojson_data)

tilecode2geo_cli()

Command-line interface for tilecode2geo supporting multiple Tilecodes.

Source code in vgrid/conversion/dggs2geo/tilecode2geo.py

def tilecode2geo_cli():
    """
    Command-line interface for tilecode2geo supporting multiple Tilecodes.
    """
    parser = argparse.ArgumentParser(
        description="Convert Tilecode(s) to Shapely Polygons"
    )
    parser.add_argument(
        "tilecode_id", nargs="+", help="Input Tilecode(s), e.g. z0x0y0 z1x1y1"
    )
    args = parser.parse_args()
    polys = tilecode2geo(args.tilecode_id)
    return polys

tilecode2geojson(tilecode_ids)

Convert Tilecode cell IDs to GeoJSON FeatureCollection.

Accepts a single tilecode_id (string) or a list of tilecode_ids. For each valid Tilecode cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

tilecode_ids : str or list of str Tilecode cell ID(s) to convert. Can be a single string or a list of strings. Format: 'z{x}x{y}y{z}' where z is zoom level and x,y are tile coordinates. Example format: "z0x0y0"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid Tilecode cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the Tilecode cell ID, resolution level, and cell metadata

Examples

tilecode2geojson("z0x0y0")

tilecode2geojson(["z0x0y0", "z1x1y1"])

Source code in vgrid/conversion/dggs2geo/tilecode2geo.py

def tilecode2geojson(tilecode_ids):
    """
    Convert Tilecode cell IDs to GeoJSON FeatureCollection.

    Accepts a single tilecode_id (string) or a list of tilecode_ids. For each valid Tilecode cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    tilecode_ids : str or list of str
        Tilecode cell ID(s) to convert. Can be a single string or a list of strings.
        Format: 'z{x}x{y}y{z}' where z is zoom level and x,y are tile coordinates.
        Example format: "z0x0y0"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid Tilecode cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the Tilecode cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> tilecode2geojson("z0x0y0")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> tilecode2geojson(["z0x0y0", "z1x1y1"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(tilecode_ids, str):
        tilecode_ids = [tilecode_ids]
    tilecode_features = []
    for tilecode_id in tilecode_ids:
        try:
            match = re.match(r"z(\d+)x(\d+)y(\d+)", tilecode_id)
            if not match:
                continue
            z = int(match.group(1))
            x = int(match.group(2))
            y = int(match.group(3))
            bounds = mercantile.bounds(x, y, z)
            cell_polygon = tilecode2geo(tilecode_id)
            if bounds:
                min_lat, min_lon = bounds.south, bounds.west
                max_lat, max_lon = bounds.north, bounds.east
                cell_polygon = Polygon(
                    [
                        [min_lon, min_lat],
                        [max_lon, min_lat],
                        [max_lon, max_lat],
                        [min_lon, max_lat],
                        [min_lon, min_lat],
                    ]
                )
                resolution = z
                tilecode_feature = graticule_dggs_to_feature(
                    "tilecode_id", tilecode_id, resolution, cell_polygon
                )
                tilecode_features.append(tilecode_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": tilecode_features}

tilecode2geojson_cli()

Command-line interface for tilecode2geojson supporting multiple Tilecodes.

Source code in vgrid/conversion/dggs2geo/tilecode2geo.py

def tilecode2geojson_cli():
    """
    Command-line interface for tilecode2geojson supporting multiple Tilecodes.
    """
    parser = argparse.ArgumentParser(description="Convert Tilecode(s) to GeoJSON")
    parser.add_argument(
        "tilecode_id", nargs="+", help="Input Tilecode(s), e.g. z0x0y0 z1x1y1"
    )
    args = parser.parse_args()
    geojson_data = json.dumps(tilecode2geojson(args.tilecode_id))
    print(geojson_data)

H3 to Geometry Module

This module provides functionality to convert H3 cell IDs to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

h32geo(h3_ids, fix_antimeridian=None)

Convert H3 cell IDs to Shapely geometry objects.

Accepts a single h3_id (string) or a list of h3_ids. For each valid H3 cell ID, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

h3_ids : str or list of str H3 cell ID(s) to convert. Can be a single string or a list of strings. Example format: "8e65b56628e0d07" fix_antimeridian : str, optional When 'shift' or 'shift_balanced', apply balanced antimeridian shifting. When 'shift_west', apply westward antimeridian shifting. When 'shift_east', apply eastward antimeridian shifting. When 'split', apply antimeridian splitting to the resulting polygons. When None or not provided, do not apply any antimeridian fixing. Defaults to None.

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single H3 cell ID is provided, returns a single Shapely Polygon object. If a list of IDs is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding H3 cell.

Examples

h32geo("8e65b56628e0d07")

h32geo(["8e65b56628e0d07", "8e65b56628e6adf"]) [, ]

Source code in vgrid/conversion/dggs2geo/h32geo.py

def h32geo(h3_ids, fix_antimeridian: str = None):
    """
    Convert H3 cell IDs to Shapely geometry objects.

    Accepts a single h3_id (string) or a list of h3_ids. For each valid H3 cell ID,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    h3_ids : str or list of str
        H3 cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "8e65b56628e0d07"
    fix_antimeridian : str, optional
        When 'shift' or 'shift_balanced', apply balanced antimeridian shifting.
        When 'shift_west', apply westward antimeridian shifting.
        When 'shift_east', apply eastward antimeridian shifting.
        When 'split', apply antimeridian splitting to the resulting polygons.
        When None or not provided, do not apply any antimeridian fixing.
        Defaults to None.

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single H3 cell ID is provided, returns a single Shapely Polygon object.
        If a list of IDs is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding H3 cell.

    Examples
    --------
    >>> h32geo("8e65b56628e0d07")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> h32geo(["8e65b56628e0d07", "8e65b56628e6adf"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(h3_ids, str):
        h3_ids = [h3_ids]
    h3_polygons = []
    for h3_id in h3_ids:
        try:
            cell_boundary = h3.cell_to_boundary(h3_id)
            reversed_boundary = [(lon, lat) for lat, lon in cell_boundary]
            cell_polygon = Polygon(reversed_boundary)

            # Apply antimeridian fixing only if fix_antimeridian is provided
            if fix_antimeridian == "shift" or fix_antimeridian == "shift_balanced":
                cell_polygon = shift_balanced(
                    cell_polygon, threshold_west=-130, threshold_east=146
                )
            elif fix_antimeridian == "shift_west":
                cell_polygon = shift_west(cell_polygon, threshold=-130)
            elif fix_antimeridian == "shift_east":
                cell_polygon = shift_east(
                    cell_polygon, threshold=146
                )  # try 145 (top) to 146(bottom), 145.5 (both)
            elif fix_antimeridian == "split":
                cell_polygon = fix_polygon(cell_polygon)

            h3_polygons.append(cell_polygon)

        except Exception:
            continue
    if len(h3_polygons) == 1:
        return h3_polygons[0]
    return h3_polygons

h32geo_cli()

Command-line interface for h32geo supporting multiple H3 cell IDs.

Source code in vgrid/conversion/dggs2geo/h32geo.py

def h32geo_cli():
    """
    Command-line interface for h32geo supporting multiple H3 cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert H3 cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "h3",
        nargs="+",
        help="Input H3 cell ID(s), e.g., h32geo 8e65b56628e0d07 8e65b56628e6adf",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    polys = h32geo(args.h3, fix_antimeridian=args.fix_antimeridian)
    return polys

h32geojson(h3_ids, fix_antimeridian=None)

Convert H3 cell IDs to GeoJSON FeatureCollection.

Accepts a single h3_id (string) or a list of h3_ids. For each valid H3 cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

h3_ids : str or list of str H3 cell ID(s) to convert. Can be a single string or a list of strings. Example format: "8e65b56628e0d07" fix_antimeridian : str, optional When 'shift' or 'shift_balanced', apply balanced antimeridian shifting. When 'shift_west', apply westward antimeridian shifting. When 'shift_east', apply eastward antimeridian shifting. When 'split', apply antimeridian splitting to the resulting polygons. When None or not provided, do not apply any antimeridian fixing. Defaults to None.

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid H3 cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the H3 cell ID, resolution level, and cell metadata

Examples

h32geojson("8e65b56628e0d07")

h32geojson(["8e65b56628e0d07", "8e65b56628e6adf"])

Source code in vgrid/conversion/dggs2geo/h32geo.py

def h32geojson(h3_ids, fix_antimeridian=None):
    """
    Convert H3 cell IDs to GeoJSON FeatureCollection.

    Accepts a single h3_id (string) or a list of h3_ids. For each valid H3 cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    h3_ids : str or list of str
        H3 cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "8e65b56628e0d07"
    fix_antimeridian : str, optional
        When 'shift' or 'shift_balanced', apply balanced antimeridian shifting.
        When 'shift_west', apply westward antimeridian shifting.
        When 'shift_east', apply eastward antimeridian shifting.
        When 'split', apply antimeridian splitting to the resulting polygons.
        When None or not provided, do not apply any antimeridian fixing.
        Defaults to None.

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid H3 cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the H3 cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> h32geojson("8e65b56628e0d07")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> h32geojson(["8e65b56628e0d07", "8e65b56628e6adf"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(h3_ids, str):
        h3_ids = [h3_ids]
    h3_features = []
    for h3_id in h3_ids:
        try:
            cell_polygon = h32geo(h3_id, fix_antimeridian=fix_antimeridian)
            resolution = h3_id
            num_edges = 6
            if h3.is_pentagon(h3_id):
                num_edges = 5
            h3_feature = geodesic_dggs_to_feature(
                "h3", h3_id, resolution, cell_polygon, num_edges
            )
            h3_features.append(h3_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": h3_features}

h32geojson_cli()

Command-line interface for h32geojson supporting multiple H3 cell IDs.

Source code in vgrid/conversion/dggs2geo/h32geo.py

def h32geojson_cli():
    """
    Command-line interface for h32geojson supporting multiple H3 cell IDs.
    """
    parser = argparse.ArgumentParser(description="Convert H3 cell ID(s) to GeoJSON")
    parser.add_argument(
        "h3",
        nargs="+",
        help="Input H3 cell ID(s), e.g., h32geojson 8e65b56628e0d07 8e65b56628e6adf",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(
        h32geojson(args.h3, fix_antimeridian=args.fix_antimeridian)
    )
    print(geojson_data)

S2 to Geometry Module

This module provides functionality to convert S2 cell tokens to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

s22geo(s2_tokens, fix_antimeridian=None)

Convert S2 cell tokens to Shapely geometry objects.

Accepts a single s2_token (string) or a list of s2_tokens. For each valid S2 cell token, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

s2_tokens : str or list of str S2 cell token(s) to convert. Can be a single string or a list of strings. Example format: "31752f45cc94" fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none Returns

---

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single S2 cell token is provided, returns a single Shapely Polygon object. If a list of tokens is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding S2 cell.

Examples

s22geo("31752f45cc94")

s22geo(["31752f45cc94", "31752f45cc95"]) [, ]

Source code in vgrid/conversion/dggs2geo/s22geo.py

def s22geo(s2_tokens, fix_antimeridian=None):
    """
    Convert S2 cell tokens to Shapely geometry objects.

    Accepts a single s2_token (string) or a list of s2_tokens. For each valid S2 cell token,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    s2_tokens : str or list of str
        S2 cell token(s) to convert. Can be a single string or a list of strings.
        Example format: "31752f45cc94"
    fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none
    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single S2 cell token is provided, returns a single Shapely Polygon object.
        If a list of tokens is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding S2 cell.

    Examples
    --------
    >>> s22geo("31752f45cc94")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> s22geo(["31752f45cc94", "31752f45cc95"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(s2_tokens, str):
        s2_tokens = [s2_tokens]
    s2_polygons = []
    for s2_token in s2_tokens:
        try:
            cell_id = s2.CellId.from_token(s2_token)
            cell = s2.Cell(cell_id)
            vertices = [cell.get_vertex(i) for i in range(4)]
            shapely_vertices = []
            for vertex in vertices:
                lat_lng = s2.LatLng.from_point(vertex)
                longitude = lat_lng.lng().degrees
                latitude = lat_lng.lat().degrees
                shapely_vertices.append((longitude, latitude))
            shapely_vertices.append(shapely_vertices[0])
            cell_polygon = Polygon(shapely_vertices)
            if fix_antimeridian == "shift" or fix_antimeridian == "shift_balanced":
                cell_polygon = shift_balanced(
                    cell_polygon, threshold_west=-90, threshold_east=90
                )
            elif fix_antimeridian == "shift_west":
                cell_polygon = shift_west(cell_polygon, threshold=-90)
            elif fix_antimeridian == "shift_east":
                cell_polygon = shift_east(cell_polygon, threshold=90)  # 130?
            elif fix_antimeridian == "split":
                cell_polygon = fix_polygon(cell_polygon)
                # if resolution == 0:  #
                #     cell_polygon = fix_polygon(cell_polygon)
                # elif (
                #         s2_token.startswith("00")
                #         or s2_token.startswith("09")
                #         or s2_token.startswith("14")
                #         or s2_token.startswith("04")
                #         or s2_token.startswith("19")
                #     ):
                #     cell_polygon = fix_polygon(cell_polygon)
            s2_polygons.append(cell_polygon)
        except Exception:
            continue
    if len(s2_polygons) == 1:
        return s2_polygons[0]
    return s2_polygons

s22geo_cli()

Command-line interface for s22geo supporting multiple S2 cell tokens.

Source code in vgrid/conversion/dggs2geo/s22geo.py

def s22geo_cli():
    """
    Command-line interface for s22geo supporting multiple S2 cell tokens.
    """
    parser = argparse.ArgumentParser(
        description="Convert S2 cell token(s) to Shapely Polygons"
    )
    parser.add_argument(
        "s2",
        nargs="+",
        help="Input S2 cell token(s), e.g., s22geo 31752f45cc94 31752f45cc95",
    )
    args = parser.parse_args()
    polys = s22geo(args.s2)
    return polys

s22geojson(s2_tokens, fix_antimeridian=None)

Convert S2 cell tokens to GeoJSON FeatureCollection.

Accepts a single s2_token (string) or a list of s2_tokens. For each valid S2 cell token, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

s2_tokens : str or list of str S2 cell token(s) to convert. Can be a single string or a list of strings. Example format: "31752f45cc94" fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none Returns

---

dict A GeoJSON FeatureCollection containing polygon features for each valid S2 cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the S2 cell token, resolution level, and cell metadata

Examples

s22geojson("31752f45cc94")

s22geojson(["31752f45cc94", "31752f45cc95"])

Source code in vgrid/conversion/dggs2geo/s22geo.py

def s22geojson(s2_tokens, fix_antimeridian=None):
    """
    Convert S2 cell tokens to GeoJSON FeatureCollection.

    Accepts a single s2_token (string) or a list of s2_tokens. For each valid S2 cell token,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    s2_tokens : str or list of str
        S2 cell token(s) to convert. Can be a single string or a list of strings.
        Example format: "31752f45cc94"
    fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none
    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid S2 cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the S2 cell token, resolution level, and cell metadata

    Examples
    --------
    >>> s22geojson("31752f45cc94")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> s22geojson(["31752f45cc94", "31752f45cc95"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(s2_tokens, str):
        s2_tokens = [s2_tokens]
    s2_features = []
    for s2_token in s2_tokens:
        try:
            cell_id = s2.CellId.from_token(s2_token)
            cell_polygon = s22geo(s2_token, fix_antimeridian=fix_antimeridian)
            resolution = cell_id.level()
            num_edges = 4
            s2_feature = geodesic_dggs_to_feature(
                "s2", s2_token, resolution, cell_polygon, num_edges
            )
            s2_features.append(s2_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": s2_features}

s22geojson_cli()

Command-line interface for s22geojson supporting multiple S2 cell tokens.

Source code in vgrid/conversion/dggs2geo/s22geo.py

def s22geojson_cli():
    """
    Command-line interface for s22geojson supporting multiple S2 cell tokens.
    """
    parser = argparse.ArgumentParser(description="Convert S2 cell token(s) to GeoJSON")
    parser.add_argument(
        "s2",
        nargs="+",
        help="Input S2 cell token(s), e.g., s22geojson 31752f45cc94 31752f45cc95",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    fix_antimeridian = args.fix_antimeridian
    geojson_data = json.dumps(s22geojson(args.s2, fix_antimeridian=fix_antimeridian))
    print(geojson_data)

A5 to Geometry Module

This module provides functionality to convert A5 cell IDs to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

a52geo(a5_hexes, options=None, split_antimeridian=False)

Convert A5 cell IDs to Shapely geometry objects.

Accepts a single a5_id (string or int) or a list of a5_ids. For each valid A5 cell ID, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

a5_hexes : str, int, or list of str/int A5 cell ID(s) to convert. Can be a single string/int or a list of strings/ints. Example format: "8e65b56628e0d07" options : dict, optional Options to pass to a5.cell_to_boundary. Defaults to None. split_antimeridian : bool, optional When True, apply antimeridian fixing to the resulting polygons. Defaults to False when None or omitted.

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single A5 cell ID is provided, returns a single Shapely Polygon object. If a list of IDs is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding A5 cell.

Examples

a52geo("8e65b56628e0d07")

a52geo(["8e65b56628e0d07", "8e65b56628e6adf"]) [, ]

Source code in vgrid/conversion/dggs2geo/a52geo.py

def a52geo(a5_hexes, options=None, split_antimeridian=False):
    """
    Convert A5 cell IDs to Shapely geometry objects.

    Accepts a single a5_id (string or int) or a list of a5_ids. For each valid A5 cell ID,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    a5_hexes : str, int, or list of str/int
        A5 cell ID(s) to convert. Can be a single string/int or a list of strings/ints.
        Example format: "8e65b56628e0d07"
    options : dict, optional
        Options to pass to a5.cell_to_boundary. Defaults to None.
    split_antimeridian : bool, optional
        When True, apply antimeridian fixing to the resulting polygons.
        Defaults to False when None or omitted.

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single A5 cell ID is provided, returns a single Shapely Polygon object.
        If a list of IDs is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding A5 cell.

    Examples
    --------
    >>> a52geo("8e65b56628e0d07")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> a52geo(["8e65b56628e0d07", "8e65b56628e6adf"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(a5_hexes, str):
        a5_hexes = [a5_hexes]
    a5_polygons = []
    for a5_hex in a5_hexes:
        try:
            cell_u64 = a5.hex_to_u64(a5_hex)
            # options = {"segments": 1000}
            cell_boundary = a5.cell_to_boundary(cell_u64, options)  # testing equal area
            cell_polygon = Polygon(cell_boundary)
            if split_antimeridian:
                cell_polygon = fix_polygon(cell_polygon)
            a5_polygons.append(cell_polygon)
        except Exception:
            continue
    if len(a5_polygons) == 1:
        return a5_polygons[0]
    return a5_polygons

a52geo_cli()

Command-line interface for a52geo supporting multiple a5 cell IDs.

Source code in vgrid/conversion/dggs2geo/a52geo.py

def a52geo_cli():
    """
    Command-line interface for a52geo supporting multiple a5 cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert a5 cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "a5",
        nargs="+",
        help="Input a5 cell ID(s), e.g., a52geo 8e65b56628e0d07 8e65b56628e6adf",
    )
    parser.add_argument(
        "-split",
        "--split_antimeridian",
        action="store_true",
        default=True,
        help="Apply antimeridian fixing to the resulting polygons",
    )
    args = parser.parse_args()
    polys = a52geo(args.a5, split_antimeridian=args.split_antimeridian)
    return polys

a52geojson(a5_hexes, options=None, split_antimeridian=False)

Convert A5 cell IDs to GeoJSON FeatureCollection.

Accepts a single a5_id (string or int) or a list of a5_ids. For each valid A5 cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

a5_hexes : str, int, or list of str/int A5 cell ID(s) to convert. Can be a single string/int or a list of strings/ints. Example format: "8e65b56628e0d07" options : dict, optional Options to pass to a5.cell_to_boundary. Defaults to None. split_antimeridian : bool, optional When True, apply antimeridian fixing to the resulting polygons. Defaults to False when None or omitted.

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid A5 cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the A5 cell ID, resolution level, and cell metadata

Examples

a52geojson("8e65b56628e0d07")

a52geojson(["8e65b56628e0d07", "8e65b56628e6adf"])

Source code in vgrid/conversion/dggs2geo/a52geo.py

def a52geojson(a5_hexes, options=None, split_antimeridian=False):
    """
    Convert A5 cell IDs to GeoJSON FeatureCollection.

    Accepts a single a5_id (string or int) or a list of a5_ids. For each valid A5 cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    a5_hexes : str, int, or list of str/int
        A5 cell ID(s) to convert. Can be a single string/int or a list of strings/ints.
        Example format: "8e65b56628e0d07"
    options : dict, optional
        Options to pass to a5.cell_to_boundary. Defaults to None.
    split_antimeridian : bool, optional
        When True, apply antimeridian fixing to the resulting polygons.
        Defaults to False when None or omitted.

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid A5 cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the A5 cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> a52geojson("8e65b56628e0d07")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> a52geojson(["8e65b56628e0d07", "8e65b56628e6adf"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    # Handle single input (string or int)
    if isinstance(a5_hexes, str):
        a5_hexes = [a5_hexes]

    a5_features = []
    for a5_hex in a5_hexes:
        try:
            cell_polygon = a52geo(
                a5_hex, options, split_antimeridian=split_antimeridian
            )
            num_edges = 5
            resolution = a5.get_resolution(a5.hex_to_u64(a5_hex))
            a5_feature = geodesic_dggs_to_feature(
                "a5", a5_hex, resolution, cell_polygon, num_edges
            )
            a5_features.append(a5_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": a5_features}

a52geojson_cli()

Command-line interface for a52geojson supporting multiple A5 cell hex.

Source code in vgrid/conversion/dggs2geo/a52geo.py

def a52geojson_cli():
    """
    Command-line interface for a52geojson supporting multiple A5 cell hex.
    """
    parser = argparse.ArgumentParser(description="Convert A5 cell hex to GeoJSON")
    parser.add_argument(
        "a5",
        nargs="+",
        help="Input a5 cell hex, e.g., a52geojson 8e65b56628e0d07 8e65b56628e6adf",
    )
    parser.add_argument(
        "-split",
        "--split_antimeridian",
        action="store_true",
        default=False,
        help="Enable Antimeridian splitting",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(
        a52geojson(args.a5, split_antimeridian=args.split_antimeridian)
    )
    print(geojson_data)

RHEALPix to Geometry Module

This module provides functionality to convert RHEALPix (Rectified HEALPix) cell IDs to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

rhealpix2geo(rhealpix_ids, fix_antimeridian=None)

Convert RHEALPix cell IDs to Shapely geometry objects.

Accepts a single rhealpix_id (string) or a list of rhealpix_ids. For each valid RHEALPix cell ID, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

rhealpix_ids : str or list of str RHEALPix cell ID(s) to convert. Can be a single string or a list of strings. Each ID should be a string starting with 'R' followed by numeric digits. Example format: "R31260335553825" fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none When True, apply antimeridian fixing to the resulting polygons. Defaults to False when None or omitted.

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single RHEALPix cell ID is provided, returns a single Shapely Polygon object. If a list of IDs is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding RHEALPix cell.

Examples

rhealpix2geo("R31260335553825")

rhealpix2geo(["R31260335553825", "R31260335553826"]) [, ]

Source code in vgrid/conversion/dggs2geo/rhealpix2geo.py

def rhealpix2geo(rhealpix_ids, fix_antimeridian=None):
    """
    Convert RHEALPix cell IDs to Shapely geometry objects.

    Accepts a single rhealpix_id (string) or a list of rhealpix_ids. For each valid RHEALPix cell ID,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    rhealpix_ids : str or list of str
        RHEALPix cell ID(s) to convert. Can be a single string or a list of strings.
        Each ID should be a string starting with 'R' followed by numeric digits.
        Example format: "R31260335553825"
    fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none
        When True, apply antimeridian fixing to the resulting polygons.
        Defaults to False when None or omitted.

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single RHEALPix cell ID is provided, returns a single Shapely Polygon object.
        If a list of IDs is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding RHEALPix cell.

    Examples
    --------
    >>> rhealpix2geo("R31260335553825")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> rhealpix2geo(["R31260335553825", "R31260335553826"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(rhealpix_ids, str):
        rhealpix_ids = [rhealpix_ids]
    rhealpix_polygons = []
    for rhealpix_id in rhealpix_ids:
        try:
            rhealpix_uids = (rhealpix_id[0],) + tuple(map(int, rhealpix_id[1:]))
            rhealpix_cell = rhealpix_dggs.cell(rhealpix_uids)
            cell_polygon = rhealpix_cell_to_polygon(rhealpix_cell)
            if fix_antimeridian == "shift" or fix_antimeridian == "shift_balanced":
                cell_polygon = shift_balanced(
                    cell_polygon, threshold_west=-149, threshold_east=149
                )
            elif fix_antimeridian == "shift_west":
                cell_polygon = shift_west(cell_polygon, threshold=-149)
            elif fix_antimeridian == "shift_east":
                cell_polygon = shift_east(cell_polygon, threshold=149)
            elif fix_antimeridian == "split":
                cell_polygon = fix_polygon(cell_polygon)
            rhealpix_polygons.append(cell_polygon)
        except Exception:
            continue
    if len(rhealpix_polygons) == 1:
        return rhealpix_polygons[0]
    return rhealpix_polygons

rhealpix2geo_cli()

Command-line interface for converting RHEALPix cell IDs to Shapely Polygons.

This function provides a command-line interface that accepts multiple RHEALPix cell IDs as command-line arguments and returns the corresponding Shapely Polygon objects.

Returns:

Name	Type	Description
list		A list of Shapely Polygon objects representing the converted cells.

Usage

rhealpix2geo R31260335553825 R31260335553826

Note

This function is designed to be called from the command line and will parse arguments using argparse. Invalid cell IDs are silently skipped.

Source code in vgrid/conversion/dggs2geo/rhealpix2geo.py

def rhealpix2geo_cli():
    """
    Command-line interface for converting RHEALPix cell IDs to Shapely Polygons.

    This function provides a command-line interface that accepts multiple RHEALPix
    cell IDs as command-line arguments and returns the corresponding Shapely
    Polygon objects.

    Returns:
        list: A list of Shapely Polygon objects representing the converted cells.

    Usage:
        rhealpix2geo R31260335553825 R31260335553826

    Note:
        This function is designed to be called from the command line and will
        parse arguments using argparse. Invalid cell IDs are silently skipped.
    """
    parser = argparse.ArgumentParser(
        description="Convert Rhealpix cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "rhealpix",
        nargs="+",
        help="Input Rhealpix cell ID(s), e.g., rhealpix2geo R31260335553825 R31260335553826",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    polys = rhealpix2geo(args.rhealpix, fix_antimeridian=args.fix_antimeridian)
    return polys

rhealpix2geojson(rhealpix_ids, fix_antimeridian=None)

Convert RHEALPix cell IDs to GeoJSON FeatureCollection.

Accepts a single rhealpix_id (string) or a list of rhealpix_ids. For each valid RHEALPix cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

rhealpix_ids : str or list of str RHEALPix cell ID(s) to convert. Can be a single string or a list of strings. Each ID should be a string starting with 'R' followed by numeric digits. Example format: "R31260335553825" fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none When True, apply antimeridian fixing to the resulting polygons. Defaults to False when None or omitted.

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid RHEALPix cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the RHEALPix cell ID, resolution level, and cell metadata

Examples

rhealpix2geojson("R31260335553825")

rhealpix2geojson(["R31260335553825", "R31260335553826"])

Source code in vgrid/conversion/dggs2geo/rhealpix2geo.py

def rhealpix2geojson(rhealpix_ids, fix_antimeridian=None):
    """
    Convert RHEALPix cell IDs to GeoJSON FeatureCollection.

    Accepts a single rhealpix_id (string) or a list of rhealpix_ids. For each valid RHEALPix cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    rhealpix_ids : str or list of str
        RHEALPix cell ID(s) to convert. Can be a single string or a list of strings.
        Each ID should be a string starting with 'R' followed by numeric digits.
        Example format: "R31260335553825"
    fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none
        When True, apply antimeridian fixing to the resulting polygons.
        Defaults to False when None or omitted.

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid RHEALPix cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the RHEALPix cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> rhealpix2geojson("R31260335553825")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> rhealpix2geojson(["R31260335553825", "R31260335553826"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(rhealpix_ids, str):
        rhealpix_ids = [rhealpix_ids]
    rhealpix_features = []
    for rhealpix_id in rhealpix_ids:
        try:
            rhealpix_uids = (rhealpix_id[0],) + tuple(map(int, rhealpix_id[1:]))
            rhealpix_cell = rhealpix_dggs.cell(rhealpix_uids)
            resolution = rhealpix_cell.resolution
            cell_polygon = rhealpix_cell_to_polygon(rhealpix_cell)
            if fix_antimeridian == "shift" or fix_antimeridian == "shift_balanced":
                cell_polygon = shift_balanced(
                    cell_polygon, threshold_west=-128, threshold_east=160
                )
            elif fix_antimeridian == "shift_west":
                cell_polygon = shift_west(cell_polygon, threshold=-128)
            elif fix_antimeridian == "shift_east":
                cell_polygon = shift_east(cell_polygon, threshold=160)
            elif fix_antimeridian == "split":
                cell_polygon = fix_polygon(cell_polygon)
            num_edges = 4
            if rhealpix_cell.ellipsoidal_shape() == "dart":
                num_edges = 3
            rhealpix_feature = geodesic_dggs_to_feature(
                "rhealpix", rhealpix_id, resolution, cell_polygon, num_edges
            )
            rhealpix_features.append(rhealpix_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": rhealpix_features}

rhealpix2geojson_cli()

Command-line interface for converting RHEALPix cell IDs to GeoJSON.

This function provides a command-line interface that accepts multiple RHEALPix cell IDs as command-line arguments and outputs the corresponding GeoJSON FeatureCollection as a JSON string to stdout.

Usage

rhealpix2geojson R31260335553825 R31260335553826

Output

Prints a JSON string representing a GeoJSON FeatureCollection to stdout.

Example

$ python -m vgrid.conversion.dggs2geo.rhealpix2geo R31260335553825

Note

This function is designed to be called from the command line and will parse arguments using argparse. The GeoJSON output is formatted as a JSON string printed to stdout. Invalid cell IDs are silently skipped.

Source code in vgrid/conversion/dggs2geo/rhealpix2geo.py

def rhealpix2geojson_cli():
    """
    Command-line interface for converting RHEALPix cell IDs to GeoJSON.

    This function provides a command-line interface that accepts multiple RHEALPix
    cell IDs as command-line arguments and outputs the corresponding GeoJSON
    FeatureCollection as a JSON string to stdout.

    Usage:
        rhealpix2geojson R31260335553825 R31260335553826

    Output:
        Prints a JSON string representing a GeoJSON FeatureCollection to stdout.

    Example:
        $ python -m vgrid.conversion.dggs2geo.rhealpix2geo R31260335553825
        {"type": "FeatureCollection", "features": [...]}

    Note:
        This function is designed to be called from the command line and will
        parse arguments using argparse. The GeoJSON output is formatted as a
        JSON string printed to stdout. Invalid cell IDs are silently skipped.
    """
    parser = argparse.ArgumentParser(
        description="Convert Rhealpix cell ID(s) to GeoJSON"
    )
    parser.add_argument(
        "rhealpix",
        nargs="+",
        help="Input Rhealpix cell ID(s), e.g., rhealpix2geojson R31260335553825 R31260335553826",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(
        rhealpix2geojson(args.rhealpix, fix_antimeridian=args.fix_antimeridian)
    )
    print(geojson_data)

ISEA4T to Geometry Module

This module provides functionality to convert ISEA4T (Icosahedral Snyder Equal Area Aperture 4 Triangle) cell IDs to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

isea4t2geo(isea4t_ids, fix_antimeridian=None)

Convert ISEA4T cell IDs to Shapely geometry objects.

Accepts a single isea4t_id (string) or a list of isea4t_ids. For each valid ISEA4T cell ID, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

isea4t_ids : str or list of str ISEA4T cell ID(s) to convert. Can be a single string or a list of strings. Example format: "131023133313201333311333" fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single ISEA4T cell ID is provided, returns a single Shapely Polygon object. If a list of IDs is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding ISEA4T cell.

Examples

isea4t2geo("131023133313201333311333")

isea4t2geo(["131023133313201333311333", "131023133313201333311334"]) [, ]

Source code in vgrid/conversion/dggs2geo/isea4t2geo.py

def isea4t2geo(isea4t_ids, fix_antimeridian=None):
    """
    Convert ISEA4T cell IDs to Shapely geometry objects.

    Accepts a single isea4t_id (string) or a list of isea4t_ids. For each valid ISEA4T cell ID,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    isea4t_ids : str or list of str
        ISEA4T cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "131023133313201333311333"
    fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single ISEA4T cell ID is provided, returns a single Shapely Polygon object.
        If a list of IDs is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding ISEA4T cell.

    Examples
    --------
    >>> isea4t2geo("131023133313201333311333")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> isea4t2geo(["131023133313201333311333", "131023133313201333311334"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(isea4t_ids, str):
        isea4t_ids = [isea4t_ids]
    isea4t_polygons = []
    for isea4t_id in isea4t_ids:
        try:
            isea4t_cell = DggsCell(isea4t_id)
            cell_polygon = isea4t_cell_to_polygon(isea4t_cell)
            # cell_polygon = fix_isea4t_antimeridian_cells(cell_polygon)
            resolution = len(isea4t_id) - 2
            if fix_antimeridian == "shift" or fix_antimeridian == "shift_balanced":
                cell_polygon = shift_balanced(
                    cell_polygon, threshold_west=-100, threshold_east=100
                )
            elif fix_antimeridian == "shift_west":
                cell_polygon = shift_west(cell_polygon, threshold=-100)
            elif fix_antimeridian == "shift_east":
                cell_polygon = shift_east(cell_polygon, threshold=100)
            elif fix_antimeridian == "split":
                cell_polygon = fix_polygon(cell_polygon)
                # if resolution == 0:  #
                #     cell_polygon = fix_polygon(cell_polygon)
                # elif (
                #         isea4t_id.startswith("00")
                #         or isea4t_id.startswith("09")
                #         or isea4t_id.startswith("14")
                #         or isea4t_id.startswith("04")
                #         or isea4t_id.startswith("19")
                #     ):
                #     cell_polygon = fix_polygon(cell_polygon)
            isea4t_polygons.append(cell_polygon)
        except Exception:
            continue
    if len(isea4t_polygons) == 1:
        return isea4t_polygons[0]
    return isea4t_polygons

isea4t2geo_cli()

Command-line interface for isea4t2geo supporting multiple ISEA4T cell IDs.

Source code in vgrid/conversion/dggs2geo/isea4t2geo.py

def isea4t2geo_cli():
    """
    Command-line interface for isea4t2geo supporting multiple ISEA4T cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert ISEA4T cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "isea4t",
        nargs="+",
        help="Input isea4t code(s), e.g., isea4t2geo 131023133313201333311333 ...",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    if platform.system() == "Windows":
        polys = isea4t2geo(args.isea4t, fix_antimeridian=args.fix_antimeridian)
        return polys
    else:
        print("ISEA4T is only supported on Windows systems")

isea4t2geojson(isea4t_ids, fix_antimeridian=None)

Convert ISEA4T cell IDs to GeoJSON FeatureCollection.

Accepts a single isea4t_id (string) or a list of isea4t_ids. For each valid ISEA4T cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

isea4t_ids : str or list of str ISEA4T cell ID(s) to convert. Can be a single string or a list of strings. Example format: "131023133313201333311333" fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid ISEA4T cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the ISEA4T cell ID, resolution level, and cell metadata

Examples

isea4t2geojson("131023133313201333311333")

isea4t2geojson(["131023133313201333311333", "131023133313201333311334"])

Source code in vgrid/conversion/dggs2geo/isea4t2geo.py

def isea4t2geojson(isea4t_ids, fix_antimeridian=None):
    """
    Convert ISEA4T cell IDs to GeoJSON FeatureCollection.

    Accepts a single isea4t_id (string) or a list of isea4t_ids. For each valid ISEA4T cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    isea4t_ids : str or list of str
        ISEA4T cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "131023133313201333311333"
    fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid ISEA4T cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the ISEA4T cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> isea4t2geojson("131023133313201333311333")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> isea4t2geojson(["131023133313201333311333", "131023133313201333311334"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(isea4t_ids, str):
        isea4t_ids = [isea4t_ids]
    isea4t_features = []
    for isea4t_id in isea4t_ids:
        try:
            cell_polygon = isea4t2geo(isea4t_id, fix_antimeridian=fix_antimeridian)
            resolution = len(isea4t_id) - 2
            num_edges = 3
            isea4t_feature = geodesic_dggs_to_feature(
                "isea4t", isea4t_id, resolution, cell_polygon, num_edges
            )
            isea4t_features.append(isea4t_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": isea4t_features}

isea4t2geojson_cli()

Command-line interface for isea4t2geojson supporting multiple ISEA4T cell IDs.

Source code in vgrid/conversion/dggs2geo/isea4t2geo.py

def isea4t2geojson_cli():
    """
    Command-line interface for isea4t2geojson supporting multiple ISEA4T cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert Open-Eaggr ISEA4T cell ID(s) to GeoJSON"
    )
    parser.add_argument(
        "isea4t",
        nargs="+",
        help="Input isea4t code(s), e.g., isea4t2geojson 131023133313201333311333 ...",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    if platform.system() == "Windows":
        geojson_data = json.dumps(
            isea4t2geojson(args.isea4t, fix_antimeridian=args.fix_antimeridian)
        )
        print(geojson_data)
    else:
        print("ISEA4T is only supported on Windows systems")

ISEA3H to Geometry Module

This module provides functionality to convert ISEA3H (Icosahedral Snyder Equal Area Aperture 3 Hexagon) cell IDs to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

isea3h2geo(isea3h_ids, fix_antimeridian=None)

Convert ISEA3H cell IDs to Shapely geometry objects.

Accepts a single isea3h_id (string) or a list of isea3h_ids. For each valid ISEA3H cell ID, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

isea3h_ids : str or list of str ISEA3H cell ID(s) to convert. Can be a single string or a list of strings. Example format: "1327916769,-55086" fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single ISEA3H cell ID is provided, returns a single Shapely Polygon object. If a list of IDs is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding ISEA3H cell.

Examples

isea3h2geo("1327916769,-55086")

isea3h2geo(["1327916769,-55086", "1327916770,-55087"]) [, ]

Source code in vgrid/conversion/dggs2geo/isea3h2geo.py

def isea3h2geo(isea3h_ids, fix_antimeridian=None):
    """
    Convert ISEA3H cell IDs to Shapely geometry objects.

    Accepts a single isea3h_id (string) or a list of isea3h_ids. For each valid ISEA3H cell ID,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    isea3h_ids : str or list of str
        ISEA3H cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "1327916769,-55086"
    fix_antimeridian : Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single ISEA3H cell ID is provided, returns a single Shapely Polygon object.
        If a list of IDs is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding ISEA3H cell.

    Examples
    --------
    >>> isea3h2geo("1327916769,-55086")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> isea3h2geo(["1327916769,-55086", "1327916770,-55087"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(isea3h_ids, str):
        isea3h_ids = [isea3h_ids]
    isea3h_polygons = []
    for isea3h_id in isea3h_ids:
        try:
            isea3h_cell = DggsCell(isea3h_id)
            cell_polygon = isea3h_cell_to_polygon(isea3h_cell)
            if fix_antimeridian == "shift" or fix_antimeridian == "shift_balanced":
                cell_polygon = shift_balanced(cell_polygon)
            elif fix_antimeridian == "shift_west":
                cell_polygon = shift_west(cell_polygon)
            elif fix_antimeridian == "shift_east":
                cell_polygon = shift_east(cell_polygon)
            elif fix_antimeridian == "split":
                cell_polygon = fix_polygon(cell_polygon)

            isea3h_polygons.append(cell_polygon)
        except Exception:
            continue

    if len(isea3h_polygons) == 1:
        return isea3h_polygons[0]
    return isea3h_polygons

isea3h2geo_cli()

Command-line interface for isea3h2geo supporting multiple ISEA3H cell IDs.

Source code in vgrid/conversion/dggs2geo/isea3h2geo.py

def isea3h2geo_cli():
    """
    Command-line interface for isea3h2geo supporting multiple ISEA3H cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert ISEA3H cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "isea3h",
        nargs="+",
        help="Input ISEA3H cell ID(s), e.g., isea3h2geo 1327916769,-55086 ...",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    if platform.system() == "Windows":
        polys = isea3h2geo(args.isea3h, fix_antimeridian=args.fix_antimeridian)
        return polys
    else:
        print("ISEA3H is only supported on Windows systems")

isea3h2geojson(isea3h_ids, fix_antimeridian=None)

Convert ISEA3H cell IDs to GeoJSON FeatureCollection.

Accepts a single isea3h_id (string) or a list of isea3h_ids. For each valid ISEA3H cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

isea3h_ids : str or list of str ISEA3H cell ID(s) to convert. Can be a single string or a list of strings. Example format: "1327916769,-55086" fix_antimeridian : str, optional Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid ISEA3H cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the ISEA3H cell ID, resolution level, center coordinates, edge length, and cell area

Examples

isea3h2geojson("1327916769,-55086")

isea3h2geojson(["1327916769,-55086", "1327916770,-55087"])

Source code in vgrid/conversion/dggs2geo/isea3h2geo.py

def isea3h2geojson(isea3h_ids, fix_antimeridian=None):
    """
    Convert ISEA3H cell IDs to GeoJSON FeatureCollection.

    Accepts a single isea3h_id (string) or a list of isea3h_ids. For each valid ISEA3H cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    isea3h_ids : str or list of str
        ISEA3H cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "1327916769,-55086"
    fix_antimeridian : str, optional
        Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid ISEA3H cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the ISEA3H cell ID, resolution level, center coordinates, edge length, and cell area

    Examples
    --------
    >>> isea3h2geojson("1327916769,-55086")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> isea3h2geojson(["1327916769,-55086", "1327916770,-55087"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(isea3h_ids, str):
        isea3h_ids = [isea3h_ids]
    features = []
    for isea3h_id in isea3h_ids:
        try:
            isea3h_cell = DggsCell(isea3h_id)
            cell_polygon = isea3h2geo(isea3h_id)
            if fix_antimeridian:
                cell_polygon = fix_polygon(cell_polygon)
            cell_centroid = cell_polygon.centroid
            center_lat = cell_centroid.y
            center_lon = cell_centroid.x
            cell_area = abs(geod.geometry_area_perimeter(cell_polygon)[0])
            cell_perimeter = abs(geod.geometry_area_perimeter(cell_polygon)[1])
            isea3h2point = isea3h_dggs.convert_dggs_cell_to_point(isea3h_cell)
            cell_accuracy = isea3h2point._accuracy
            avg_edge_len = cell_perimeter / 6
            cell_resolution = ISEA3H_ACCURACY_RES_DICT.get(cell_accuracy)
            if cell_resolution == 0:
                avg_edge_len = cell_perimeter / 3
            if cell_accuracy == 0.0:
                if round(avg_edge_len, 2) == 0.06:
                    cell_resolution = 33
                elif round(avg_edge_len, 2) == 0.03:
                    cell_resolution = 34
                elif round(avg_edge_len, 2) == 0.02:
                    cell_resolution = 35
                elif round(avg_edge_len, 2) == 0.01:
                    cell_resolution = 36
                elif round(avg_edge_len, 3) == 0.007:
                    cell_resolution = 37
                elif round(avg_edge_len, 3) == 0.004:
                    cell_resolution = 38
                elif round(avg_edge_len, 3) == 0.002:
                    cell_resolution = 39
                elif round(avg_edge_len, 3) <= 0.001:
                    cell_resolution = 40
            feature = {
                "type": "Feature",
                "geometry": mapping(cell_polygon),
                "properties": {
                    "isea3h": isea3h_id,
                    "resolution": cell_resolution,
                    "center_lat": center_lat,
                    "center_lon": center_lon,
                    "avg_edge_len": round(avg_edge_len, 3),
                    "cell_area": cell_area,
                },
            }
            features.append(feature)
        except Exception:
            continue
    feature_collection = {"type": "FeatureCollection", "features": features}
    return feature_collection

isea3h2geojson_cli()

Command-line interface for isea3h2geojson supporting multiple ISEA3H cell IDs.

Source code in vgrid/conversion/dggs2geo/isea3h2geo.py

def isea3h2geojson_cli():
    """
    Command-line interface for isea3h2geojson supporting multiple ISEA3H cell IDs.
    """
    parser = argparse.ArgumentParser(description="Convert ISEA3H ID(s) to GeoJSON")
    parser.add_argument(
        "isea3h",
        nargs="+",
        help="Input ISEA3H cell ID(s), e.g., isea3h2geojson 1327916769,-55086 ...",
    )
    parser.add_argument(
        "-fix",
        "--fix_antimeridian",
        type=str,
        choices=[
            "shift",
            "shift_balanced",
            "shift_west",
            "shift_east",
            "split",
            "none",
        ],
        default=None,
        help="Antimeridian fixing method: shift, shift_balanced, shift_west, shift_east, split, none",
    )
    args = parser.parse_args()
    if platform.system() == "Windows":
        geojson_data = json.dumps(
            isea3h2geojson(args.isea3h, fix_antimeridian=args.fix_antimeridian)
        )
        print(geojson_data)
    else:
        print("ISEA3H is only supported on Windows systems")

EASE-DGGS to Geometry Module

This module provides functionality to convert EASE-DGGS (Equal-Area Scalable Earth Grid) cell IDs to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

ease2geo(ease_ids)

Convert EASE-DGGS codes to Shapely geometry objects.

Accepts a single ease_id (string) or a list of ease_ids. For each valid EASE-DGGS code, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

ease_ids : str or list of str EASE-DGGS code(s) to convert. Can be a single string or a list of strings. Example format: "L4.165767.02.02.20.71"

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single EASE-DGGS code is provided, returns a single Shapely Polygon object. If a list of codes is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding EASE-DGGS cell.

Examples

ease2geo("L4.165767.02.02.20.71")

ease2geo(["L4.165767.02.02.20.71", "L4.165768.02.02.20.71"]) [, ]

Source code in vgrid/conversion/dggs2geo/ease2geo.py

def ease2geo(ease_ids):
    """
    Convert EASE-DGGS codes to Shapely geometry objects.

    Accepts a single ease_id (string) or a list of ease_ids. For each valid EASE-DGGS code,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    ease_ids : str or list of str
        EASE-DGGS code(s) to convert. Can be a single string or a list of strings.
        Example format: "L4.165767.02.02.20.71"

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single EASE-DGGS code is provided, returns a single Shapely Polygon object.
        If a list of codes is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding EASE-DGGS cell.

    Examples
    --------
    >>> ease2geo("L4.165767.02.02.20.71")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> ease2geo(["L4.165767.02.02.20.71", "L4.165768.02.02.20.71"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(ease_ids, str):
        ease_ids = [ease_ids]
    ease_polygons = []
    for ease_id in ease_ids:
        try:
            level = int(ease_id[1])
            level_spec = levels_specs[level]
            n_row = level_spec["n_row"]
            n_col = level_spec["n_col"]
            geo = grid_ids_to_geos([ease_id])
            center_lon, center_lat = geo["result"]["data"][0]
            cell_min_lat = center_lat - (180 / (2 * n_row))
            cell_max_lat = center_lat + (180 / (2 * n_row))
            cell_min_lon = center_lon - (360 / (2 * n_col))
            cell_max_lon = center_lon + (360 / (2 * n_col))
            cell_polygon = Polygon(
                [
                    [cell_min_lon, cell_min_lat],
                    [cell_max_lon, cell_min_lat],
                    [cell_max_lon, cell_max_lat],
                    [cell_min_lon, cell_max_lat],
                    [cell_min_lon, cell_min_lat],
                ]
            )
            ease_polygons.append(cell_polygon)
        except Exception:
            continue
    if len(ease_polygons) == 1:
        return ease_polygons[0]
    return ease_polygons

ease2geo_cli()

Command-line interface for ease2geo supporting multiple EASE-DGGS codes.

Source code in vgrid/conversion/dggs2geo/ease2geo.py

def ease2geo_cli():
    """
    Command-line interface for ease2geo supporting multiple EASE-DGGS codes.
    """
    parser = argparse.ArgumentParser(
        description="Convert EASE-DGGS code(s) to Shapely Polygons"
    )
    parser.add_argument(
        "ease",
        nargs="+",
        help="Input EASE-DGGS code(s), e.g., ease2geo L4.165767.02.02.20.71 ...",
    )
    args = parser.parse_args()
    polys = ease2geo(args.ease)
    return polys

ease2geojson(ease_ids)

Convert a list of EASE-DGGS codes to GeoJSON FeatureCollection.

Accepts a single ease_id (string) or a list of ease_ids. For each valid EASE-DGGS code, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

ease_ids : str or list of str EASE-DGGS code(s) to convert. Can be a single string or a list of strings. Example format: "L4.165767.02.02.20.71"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid EASE-DGGS cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the EASE-DGGS code, resolution level, and cell metadata

Examples

ease2geojson("L4.165767.02.02.20.71")

ease2geojson(["L4.165767.02.02.20.71", "L4.165768.02.02.20.71"])

Source code in vgrid/conversion/dggs2geo/ease2geo.py

def ease2geojson(ease_ids):
    """
    Convert a list of EASE-DGGS codes to GeoJSON FeatureCollection.

    Accepts a single ease_id (string) or a list of ease_ids. For each valid EASE-DGGS code,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    ease_ids : str or list of str
        EASE-DGGS code(s) to convert. Can be a single string or a list of strings.
        Example format: "L4.165767.02.02.20.71"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid EASE-DGGS cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the EASE-DGGS code, resolution level, and cell metadata

    Examples
    --------
    >>> ease2geojson("L4.165767.02.02.20.71")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> ease2geojson(["L4.165767.02.02.20.71", "L4.165768.02.02.20.71"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(ease_ids, str):
        ease_ids = [ease_ids]
    ease_features = []
    for ease_id in ease_ids:
        try:
            cell_polygon = ease2geo(ease_id)
            resolution = get_ease_resolution(ease_id)
            num_edges = 4
            ease_feature = geodesic_dggs_to_feature(
                "ease", ease_id, resolution, cell_polygon, num_edges
            )
            ease_features.append(ease_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": ease_features}

ease2geojson_cli()

Command-line interface for ease2geojson supporting multiple EASE-DGGS codes.

Source code in vgrid/conversion/dggs2geo/ease2geo.py

def ease2geojson_cli():
    """
    Command-line interface for ease2geojson supporting multiple EASE-DGGS codes.
    """
    parser = argparse.ArgumentParser(description="Convert EASE-DGGS code(s) to GeoJSON")
    parser.add_argument(
        "ease",
        nargs="+",
        help="Input EASE-DGGS code(s), e.g., ease2geojson L4.165767.02.02.20.71 ...",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(ease2geojson(args.ease))
    print(geojson_data)

DGGAL to Geometry Module

This module provides functionality to convert DGGAL ZoneIDs to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

dggal2geo(dggs_type, zone_ids, options={}, split_antimeridian=False)

Convert DGGAL ZoneIDs to Shapely geometry objects.

Accepts a single zone_id (string) or a list of zone_ids. For each valid DGGAL ZoneID, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

dggs_type : str DGGAL DGGS type (e.g., "isea3h", "isea4t", "rhealpix"). zone_ids : str or list of str DGGAL ZoneID(s) to convert. Can be a single string or a list of strings. Example format: "A4-0-A" options : dict, optional Additional options for the conversion process. split_antimeridian : bool, optional When True, apply antimeridian fixing to the resulting polygons. Defaults to False when None or omitted.

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single DGGAL ZoneID is provided, returns a single Shapely Polygon object. If a list of IDs is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding DGGAL cell.

Examples

dggal2geo("isea3h", "A4-0-A")

dggal2geo("isea3h", ["A4-0-A", "A4-0-B"]) [, ]

Source code in vgrid/conversion/dggs2geo/dggal2geo.py

def dggal2geo(
    dggs_type: str, zone_ids: str, options: dict = {}, split_antimeridian=False
):
    """
    Convert DGGAL ZoneIDs to Shapely geometry objects.

    Accepts a single zone_id (string) or a list of zone_ids. For each valid DGGAL ZoneID,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    dggs_type : str
        DGGAL DGGS type (e.g., "isea3h", "isea4t", "rhealpix").
    zone_ids : str or list of str
        DGGAL ZoneID(s) to convert. Can be a single string or a list of strings.
        Example format: "A4-0-A"
    options : dict, optional
        Additional options for the conversion process.
    split_antimeridian : bool, optional
        When True, apply antimeridian fixing to the resulting polygons.
        Defaults to False when None or omitted.

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single DGGAL ZoneID is provided, returns a single Shapely Polygon object.
        If a list of IDs is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding DGGAL cell.

    Examples
    --------
    >>> dggal2geo("isea3h", "A4-0-A")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> dggal2geo("isea3h", ["A4-0-A", "A4-0-B"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(zone_ids, str):
        zone_ids = [zone_ids]
    zone_polygons = []
    for zone_id in zone_ids:
        try:
            zone_polygon = dggal_to_geo(dggs_type, zone_id, options)
            if zone_polygon and split_antimeridian:
                zone_polygon = fix_polygon(zone_polygon)
            if zone_polygon:
                zone_polygons.append(zone_polygon)
        except Exception:
            continue
    if len(zone_polygons) == 1:
        return zone_polygons[0]
    return zone_polygons

dggal2geojson(dggs_type, zone_ids, options={}, split_antimeridian=False)

Convert DGGAL ZoneIDs to GeoJSON FeatureCollection.

Accepts a single zone_id (string) or a list of zone_ids. For each valid DGGAL ZoneID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

dggs_type : str DGGAL DGGS type (e.g., "isea3h", "isea4t", "rhealpix"). zone_ids : str or list of str DGGAL ZoneID(s) to convert. Can be a single string or a list of strings. Example format: "A4-0-A" options : dict, optional Additional options for the conversion process. split_antimeridian : bool, optional When True, apply antimeridian fixing to the resulting polygons. Defaults to False when None or omitted.

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid DGGAL cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the DGGAL ZoneID, resolution level, and cell metadata

Examples

dggal2geojson("isea3h", "A4-0-A")

dggal2geojson("isea3h", ["A4-0-A", "A4-0-B"])

Source code in vgrid/conversion/dggs2geo/dggal2geo.py

def dggal2geojson(
    dggs_type: str, zone_ids: str, options: dict = {}, split_antimeridian=False
):
    """
    Convert DGGAL ZoneIDs to GeoJSON FeatureCollection.

    Accepts a single zone_id (string) or a list of zone_ids. For each valid DGGAL ZoneID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    dggs_type : str
        DGGAL DGGS type (e.g., "isea3h", "isea4t", "rhealpix").
    zone_ids : str or list of str
        DGGAL ZoneID(s) to convert. Can be a single string or a list of strings.
        Example format: "A4-0-A"
    options : dict, optional
        Additional options for the conversion process.
    split_antimeridian : bool, optional
        When True, apply antimeridian fixing to the resulting polygons.
        Defaults to False when None or omitted.

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid DGGAL cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the DGGAL ZoneID, resolution level, and cell metadata

    Examples
    --------
    >>> dggal2geojson("isea3h", "A4-0-A")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> dggal2geojson("isea3h", ["A4-0-A", "A4-0-B"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    dggs_type = validate_dggal_type(dggs_type)
    # Create the appropriate DGGS instance
    dggs_class_name = DGGAL_TYPES[dggs_type]["class_name"]
    dggrs = globals()[dggs_class_name]()

    if isinstance(zone_ids, str):
        zone_ids = [zone_ids]
    zone_features = []

    for zone_id in zone_ids:
        try:
            zone = dggrs.getZoneFromTextID(zone_id)
            resolution = dggrs.getZoneLevel(zone)
            num_edges = dggrs.countZoneEdges(zone)
            cell_polygon = dggal2geo(
                dggs_type, zone_id, options, split_antimeridian=split_antimeridian
            )
            zone_feature = geodesic_dggs_to_feature(
                f"dggal_{dggs_type}", zone_id, resolution, cell_polygon, num_edges
            )
            zone_features.append(zone_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": zone_features}

dggal2geojson_cli()

Command-line interface for converting DGGAL ZoneIDs to GeoJSON.

This function provides a command-line interface that accepts multiple DGGAL ZoneIDs as command-line arguments and outputs the corresponding GeoJSON FeatureCollection as a JSON string to stdout.

Usage

dggal2geojson isea3h A4-0-A A4-0-B

Output

Prints a JSON string representing a GeoJSON FeatureCollection to stdout.

Example

$ python -m vgrid.conversion.dggs2geo.dggal2geo isea3h A4-0-A

Note

This function is designed to be called from the command line and will parse arguments using argparse. The GeoJSON output is formatted as a JSON string printed to stdout. Invalid cell IDs are silently skipped.

Source code in vgrid/conversion/dggs2geo/dggal2geo.py

def dggal2geojson_cli():
    """
    Command-line interface for converting DGGAL ZoneIDs to GeoJSON.

    This function provides a command-line interface that accepts multiple DGGAL
    ZoneIDs as command-line arguments and outputs the corresponding GeoJSON
    FeatureCollection as a JSON string to stdout.

    Usage:
        dggal2geojson isea3h A4-0-A A4-0-B

    Output:
        Prints a JSON string representing a GeoJSON FeatureCollection to stdout.

    Example:
        $ python -m vgrid.conversion.dggs2geo.dggal2geo isea3h A4-0-A
        {"type": "FeatureCollection", "features": [...]}

    Note:
        This function is designed to be called from the command line and will
        parse arguments using argparse. The GeoJSON output is formatted as a
        JSON string printed to stdout. Invalid cell IDs are silently skipped.
    """
    parser = argparse.ArgumentParser(description="Convert DGGAL ZoneID(s) to GeoJSON")
    parser.add_argument(
        "dggs_type", type=str, choices=DGGAL_TYPES.keys(), help="DGGAL DGGS type"
    )
    parser.add_argument(
        "zone_id",
        nargs="+",
        help="Input DGGAL ZoneID(s), e.g., dggal2geojson isea3h A4-0-A A4-0-B",
    )
    parser.add_argument(
        "-split",
        "--split_antimeridian",
        action="store_true",
        default=False,
        help="Enable Antimeridian splitting",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(
        dggal2geojson(
            args.dggs_type, args.zone_id, split_antimeridian=args.split_antimeridian
        )
    )
    print(geojson_data)  # print to stdout

DGGRID to Geometry Module

This module provides functionality to convert DGGRID cell IDs to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

dggrid2geo(dggrid_instance, dggs_type, dggrid_ids, resolution=None, input_address_type='SEQNUM', split_antimeridian=False, aggregate=False)

Convert DGGRID cell IDs to Shapely geometry objects.

Accepts a single dggrid_id (string/int) or a list of dggrid_ids. For each valid DGGRID cell ID, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

dggrid_instance : object DGGRID instance for processing. dggs_type : str DGGRID DGGS type (e.g., "ISEA7H", "ISEA4T"). dggrid_ids : str, int, or list of str/int DGGRID cell ID(s) to convert. Can be a single string/int or a list of strings/ints. Example format: "783229476878" resolution : int, optional Resolution level for the DGGS. If None, will be validated based on dggs_type. input_address_type : str, default "SEQNUM" Input address type for the cell IDs. split_antimeridian : bool, optional When True, apply antimeridian fixing to the resulting polygons. Defaults to False when None or omitted.

Returns

geopandas.GeoDataFrame A GeoDataFrame containing polygon geometries for each valid DGGRID cell. Each row includes: - geometry: Polygon representing the cell boundaries - dggrid_{dggs_type.lower()}: The original cell ID - resolution: The resolution level

Examples

dggrid2geo(instance, "ISEA7H", "783229476878", 13)

dggrid2geo(instance, "ISEA7H", ["783229476878", "783229476879"], 13)

Source code in vgrid/conversion/dggs2geo/dggrid2geo.py

def dggrid2geo(
    dggrid_instance,
    dggs_type,
    dggrid_ids,
    resolution=None,
    input_address_type="SEQNUM",
    split_antimeridian=False,
    aggregate=False,
):
    """
    Convert DGGRID cell IDs to Shapely geometry objects.

    Accepts a single dggrid_id (string/int) or a list of dggrid_ids. For each valid DGGRID cell ID,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    dggrid_instance : object
        DGGRID instance for processing.
    dggs_type : str
        DGGRID DGGS type (e.g., "ISEA7H", "ISEA4T").
    dggrid_ids : str, int, or list of str/int
        DGGRID cell ID(s) to convert. Can be a single string/int or a list of strings/ints.
        Example format: "783229476878"
    resolution : int, optional
        Resolution level for the DGGS. If None, will be validated based on dggs_type.
    input_address_type : str, default "SEQNUM"
        Input address type for the cell IDs.
    split_antimeridian : bool, optional
        When True, apply antimeridian fixing to the resulting polygons.
        Defaults to False when None or omitted.

    Returns
    -------
    geopandas.GeoDataFrame
        A GeoDataFrame containing polygon geometries for each valid DGGRID cell.
        Each row includes:
        - geometry: Polygon representing the cell boundaries
        - dggrid_{dggs_type.lower()}: The original cell ID
        - resolution: The resolution level

    Examples
    --------
    >>> dggrid2geo(instance, "ISEA7H", "783229476878", 13)
    <geopandas.GeoDataFrame object at ...>

    >>> dggrid2geo(instance, "ISEA7H", ["783229476878", "783229476879"], 13)
    <geopandas.GeoDataFrame object at ...>
    """
    dggs_type = validate_dggrid_type(dggs_type)
    resolution = validate_dggrid_resolution(dggs_type, resolution)
    if isinstance(dggrid_ids, (str, int)):
        dggrid_ids = [dggrid_ids]

    # Convert from input_address_type to SEQNUM if needed
    if input_address_type and input_address_type != "SEQNUM":
        address_type_transform = dggrid_instance.address_transform(
            dggrid_ids,
            dggs_type=dggs_type,
            resolution=resolution,
            mixed_aperture_level=None,
            input_address_type=input_address_type,
            output_address_type="SEQNUM",
        )
        # Extract all SEQNUM values, not just the first one
        dggrid_ids = address_type_transform["SEQNUM"].tolist()

    dggrid_cells = dggrid_instance.grid_cell_polygons_from_cellids(
        dggrid_ids,
        dggs_type,
        resolution,
        split_dateline=split_antimeridian,  # to prevent polygon divided into 2 polygons
    )

    # Convert global_id back to input_address_type if needed
    if input_address_type and input_address_type != "SEQNUM":
        # Get the SEQNUM values from global_id column
        seqnum_values = dggrid_cells["global_id"].tolist()

        # Transform back to input_address_type
        reverse_transform = dggrid_instance.address_transform(
            seqnum_values,
            dggs_type=dggs_type,
            resolution=resolution,
            mixed_aperture_level=None,
            input_address_type="SEQNUM",
            output_address_type=input_address_type,
        )

        # Replace global_id values with the original input_address_type values
        dggrid_cells["global_id"] = reverse_transform[input_address_type].values

    # Rename global_id column to dggrid_{dggs_type.lower()}
    dggrid_cells = dggrid_cells.rename(
        columns={"global_id": f"dggrid_{dggs_type.lower()}"}
    )
    # Add resolution property
    dggrid_cells["resolution"] = resolution

    # Apply antimeridian fixing if requested
    if split_antimeridian:
        if aggregate:
            dggrid_cells = dggrid_cells.dissolve(by=f"dggrid_{dggs_type.lower()}")
    return dggrid_cells

dggrid2geo_cli()

Command-line interface for dggrid2geo supporting multiple DGGRID cell IDs.

Source code in vgrid/conversion/dggs2geo/dggrid2geo.py

def dggrid2geo_cli():
    """
    Command-line interface for dggrid2geo supporting multiple DGGRID cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert DGGRID cell ID(s) to Shapely Polygons. \
                                     Usage: dggrid2geo <cell_ids> <dggs_type> <res> [input_address_type]. \
                                     Ex: dggrid2geo 783229476878 ISEA7H 13 SEQNUM"
    )
    parser.add_argument(
        "dggs_type",
        choices=dggs_types,
        help="Select a DGGS type from the available options.",
    )

    parser.add_argument("dggrid_ids", nargs="+", help="Input DGGRID cell ID(s)")

    parser.add_argument("resolution", type=int, help="resolution")
    parser.add_argument(
        "input_address_type",
        choices=output_address_types,
        default="SEQNUM",
        nargs="?",  # This makes the argument optional
        help="Select an input address type from the available options.",
    )

    parser.add_argument(
        "-split",
        "--split_antimeridian",
        action="store_true",
        default=False,
        help="Apply antimeridian fixing to the resulting polygons",
    )
    parser.add_argument(
        "-aggregate",
        "--aggregate",
        action="store_true",
        help="Aggregate the resulting polygons",
    )
    args = parser.parse_args()
    dggrid_instance = create_dggrid_instance()
    polys = dggrid2geo(
        dggrid_instance,
        args.dggs_type,
        args.dggrid_ids,
        args.resolution,
        args.input_address_type,
        split_antimeridian=args.split_antimeridian,
        aggregate=args.aggregate,
    )
    return polys

dggrid2geojson(dggrid_instance, dggs_type, dggrid_ids, resolution, input_address_type='SEQNUM', split_antimeridian=False, aggregate=False)

Convert DGGRID cell IDs to GeoJSON FeatureCollection.

Accepts a single dggrid_id (string/int) or a list of dggrid_ids. For each valid DGGRID cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

dggrid_instance : object DGGRID instance for processing. dggs_type : str DGGRID DGGS type (e.g., "ISEA7H", "ISEA4T"). dggrid_ids : str, int, or list of str/int DGGRID cell ID(s) to convert. Can be a single string/int or a list of strings/ints. Example format: "783229476878" resolution : int Resolution level for the DGGS. input_address_type : str, default "SEQNUM" Input address type for the cell IDs. split_antimeridian : bool, optional When True, apply antimeridian fixing to the resulting polygons. Defaults to False when None or omitted.

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid DGGRID cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the DGGRID cell ID, resolution level, and cell metadata

Examples

dggrid2geojson(instance, "ISEA7H", "783229476878", 13)

dggrid2geojson(instance, "ISEA7H", ["783229476878", "783229476879"], 13)

Source code in vgrid/conversion/dggs2geo/dggrid2geo.py

def dggrid2geojson(
    dggrid_instance,
    dggs_type,
    dggrid_ids,
    resolution,
    input_address_type="SEQNUM",
    split_antimeridian=False,
    aggregate=False,
):
    """
    Convert DGGRID cell IDs to GeoJSON FeatureCollection.

    Accepts a single dggrid_id (string/int) or a list of dggrid_ids. For each valid DGGRID cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    dggrid_instance : object
        DGGRID instance for processing.
    dggs_type : str
        DGGRID DGGS type (e.g., "ISEA7H", "ISEA4T").
    dggrid_ids : str, int, or list of str/int
        DGGRID cell ID(s) to convert. Can be a single string/int or a list of strings/ints.
        Example format: "783229476878"
    resolution : int
        Resolution level for the DGGS.
    input_address_type : str, default "SEQNUM"
        Input address type for the cell IDs.
    split_antimeridian : bool, optional
        When True, apply antimeridian fixing to the resulting polygons.
        Defaults to False when None or omitted.

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid DGGRID cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the DGGRID cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> dggrid2geojson(instance, "ISEA7H", "783229476878", 13)
    {'type': 'FeatureCollection', 'features': [...]}

    >>> dggrid2geojson(instance, "ISEA7H", ["783229476878", "783229476879"], 13)
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(dggrid_ids, (str, int)):
        dggrid_ids = [dggrid_ids]

    # Get the GeoDataFrame from dggrid2geo
    gdf = dggrid2geo(
        dggrid_instance,
        dggs_type,
        dggrid_ids,
        resolution,
        input_address_type,
        split_antimeridian=split_antimeridian,
        aggregate=aggregate,
    )
    # Convert GeoDataFrame to GeoJSON dictionary
    geojson_dict = json.loads(gdf.to_json())

    return geojson_dict

dggrid2geojson_cli()

Command-line interface for dggrid2geojson supporting multiple DGGRID cell IDs.

Source code in vgrid/conversion/dggs2geo/dggrid2geo.py

def dggrid2geojson_cli():
    """
    Command-line interface for dggrid2geojson supporting multiple DGGRID cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert DGGRID cell ID(s) to GeoJSON. \
                                     Usage: dggrid2geojson <cell_ids> <dggs_type> <res> [input_address_type]. \
                                     Ex: dggrid2geojson 783229476878 ISEA7H 13 SEQNUM"
    )

    parser.add_argument(
        "dggs_type",
        choices=dggs_types,
        help="Select a DGGS type from the available options.",
    )
    parser.add_argument("dggrid_ids", nargs="+", help="Input DGGRID cell ID(s)")
    parser.add_argument("resolution", type=int, help="resolution")
    parser.add_argument(
        "input_address_type",
        choices=output_address_types,
        default="SEQNUM",
        nargs="?",  # This makes the argument optional
        help="Select an input address type from the available options.",
    )
    parser.add_argument(
        "-split",
        "--split_antimeridian",
        action="store_true",
        default=True,
        help="Enable Antimeridian splitting",
    )
    parser.add_argument(
        "-aggregate",
        "--aggregate",
        action="store_true",
        help="Aggregate the resulting polygons",
    )
    args = parser.parse_args()
    dggrid_instance = create_dggrid_instance()
    geojson_data = json.dumps(
        dggrid2geojson(
            dggrid_instance,
            args.dggs_type,
            args.dggrid_ids,
            args.resolution,
            args.input_address_type,
            split_antimeridian=args.split_antimeridian,
            aggregate=args.aggregate,
        )
    )
    print(geojson_data)

QTM to Geometry Module

This module provides functionality to convert QTM (Ternary Triangular Mesh) cell IDs to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

qtm2geo(qtm_ids)

Convert QTM cell IDs to Shapely geometry objects.

Accepts a single qtm_id (string) or a list of qtm_ids. For each valid QTM cell ID, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

qtm_ids : str or list of str QTM cell ID(s) to convert. Can be a single string or a list of strings. Example format: "42012321"

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single QTM cell ID is provided, returns a single Shapely Polygon object. If a list of IDs is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding QTM cell.

Examples

qtm2geo("42012321")

qtm2geo(["42012321", "42012322"]) [, ]

Source code in vgrid/conversion/dggs2geo/qtm2geo.py

def qtm2geo(qtm_ids):
    """
    Convert QTM cell IDs to Shapely geometry objects.

    Accepts a single qtm_id (string) or a list of qtm_ids. For each valid QTM cell ID,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    qtm_ids : str or list of str
        QTM cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "42012321"

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single QTM cell ID is provided, returns a single Shapely Polygon object.
        If a list of IDs is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding QTM cell.

    Examples
    --------
    >>> qtm2geo("42012321")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> qtm2geo(["42012321", "42012322"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(qtm_ids, str):
        qtm_ids = [qtm_ids]
    qtm_polygons = []
    for qtm_id in qtm_ids:
        try:
            facet = qtm_id_to_facet(qtm_id)
            cell_polygon = constructGeometry(facet)
            qtm_polygons.append(cell_polygon)
        except Exception:
            continue
    if len(qtm_polygons) == 1:
        return qtm_polygons[0]
    return qtm_polygons

qtm2geo_cli()

Command-line interface for qtm2geo supporting multiple QTM cell IDs.

Source code in vgrid/conversion/dggs2geo/qtm2geo.py

def qtm2geo_cli():
    """
    Command-line interface for qtm2geo supporting multiple QTM cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert QTM cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "qtm",
        nargs="+",
        help="Input QTM cell ID(s), e.g., qtm2geo 42012321 42012322",
    )
    args = parser.parse_args()
    polys = qtm2geo(args.qtm)
    return polys

qtm2geojson(qtm_ids)

Convert QTM cell IDs to GeoJSON FeatureCollection.

Accepts a single qtm_id (string) or a list of qtm_ids. For each valid QTM cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

qtm_ids : str or list of str QTM cell ID(s) to convert. Can be a single string or a list of strings. Example format: "42012321"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid QTM cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the QTM cell ID, resolution level, and cell metadata

Examples

qtm2geojson("42012321")

qtm2geojson(["42012321", "42012322"])

Source code in vgrid/conversion/dggs2geo/qtm2geo.py

def qtm2geojson(qtm_ids):
    """
    Convert QTM cell IDs to GeoJSON FeatureCollection.

    Accepts a single qtm_id (string) or a list of qtm_ids. For each valid QTM cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    qtm_ids : str or list of str
        QTM cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "42012321"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid QTM cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the QTM cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> qtm2geojson("42012321")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> qtm2geojson(["42012321", "42012322"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(qtm_ids, str):
        qtm_ids = [qtm_ids]
    qtm_features = []
    for qtm_id in qtm_ids:
        try:
            cell_polygon = qtm2geo(qtm_id)
            resolution = len(qtm_id)
            num_edges = 3
            qtm_feature = geodesic_dggs_to_feature(
                "qtm", qtm_id, resolution, cell_polygon, num_edges
            )
            qtm_features.append(qtm_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": qtm_features}

qtm2geojson_cli()

Command-line interface for qtm2geojson supporting multiple QTM cell IDs.

Source code in vgrid/conversion/dggs2geo/qtm2geo.py

def qtm2geojson_cli():
    """
    Command-line interface for qtm2geojson supporting multiple QTM cell IDs.
    """
    parser = argparse.ArgumentParser(description="Convert QTM cell ID(s) to GeoJSON")
    parser.add_argument(
        "qtm",
        nargs="+",
        help="Input QTM cell ID(s), e.g., qtm2geojson 42012321 42012322",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(qtm2geojson(args.qtm))
    print(geojson_data)

OLC to Geometry Module

This module provides functionality to convert Open Location Codes (OLC), also known as Google Plus Codes, to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

olc2geo(olc_ids)

Convert OLC (Open Location Code) cell IDs to Shapely geometry objects.

Accepts a single olc_id (string) or a list of olc_ids. For each valid OLC cell ID, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

olc_ids : str or list of str OLC cell ID(s) to convert. Can be a single string or a list of strings. Example format: "7P28QPG4+4P7"

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single OLC cell ID is provided, returns a single Shapely Polygon object. If a list of IDs is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding OLC cell.

Examples

olc2geo("7P28QPG4+4P7")

olc2geo(["7P28QPG4+4P7", "7P28QPG4+4P8"]) [, ]

Source code in vgrid/conversion/dggs2geo/olc2geo.py

def olc2geo(olc_ids):
    """
    Convert OLC (Open Location Code) cell IDs to Shapely geometry objects.

    Accepts a single olc_id (string) or a list of olc_ids. For each valid OLC cell ID,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    olc_ids : str or list of str
        OLC cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "7P28QPG4+4P7"

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single OLC cell ID is provided, returns a single Shapely Polygon object.
        If a list of IDs is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding OLC cell.

    Examples
    --------
    >>> olc2geo("7P28QPG4+4P7")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> olc2geo(["7P28QPG4+4P7", "7P28QPG4+4P8"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(olc_ids, str):
        olc_ids = [olc_ids]
    olc_polygons = []
    for olc_id in olc_ids:
        try:
            coord = olc.decode(olc_id)
            min_lat, min_lon = coord.latitudeLo, coord.longitudeLo
            max_lat, max_lon = coord.latitudeHi, coord.longitudeHi
            cell_polygon = Polygon(
                [
                    [min_lon, min_lat],
                    [max_lon, min_lat],
                    [max_lon, max_lat],
                    [min_lon, max_lat],
                    [min_lon, min_lat],
                ]
            )
            olc_polygons.append(cell_polygon)
        except Exception:
            continue
    if len(olc_polygons) == 1:
        return olc_polygons[0]
    return olc_polygons

olc2geo_cli()

Command-line interface for olc2geo supporting multiple OLC codes.

Source code in vgrid/conversion/dggs2geo/olc2geo.py

def olc2geo_cli():
    """
    Command-line interface for olc2geo supporting multiple OLC codes.
    """
    parser = argparse.ArgumentParser(
        description="Convert OLC/Google Plus Codes to Shapely Polygons"
    )
    parser.add_argument(
        "olc",
        nargs="+",
        help="Input OLC(s), e.g., olc2geo 7P28QPG4+4P7 7P28QPG4+4P8",
    )
    args = parser.parse_args()
    polys = olc2geo(args.olc)
    return polys

olc2geojson(olc_ids)

Convert OLC (Open Location Code) cell IDs to GeoJSON FeatureCollection.

Accepts a single olc_id (string) or a list of olc_ids. For each valid OLC cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

olc_ids : str or list of str OLC cell ID(s) to convert. Can be a single string or a list of strings. Example format: "7P28QPG4+4P7"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid OLC cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the OLC cell ID, resolution level, and cell metadata

Examples

olc2geojson("7P28QPG4+4P7")

olc2geojson(["7P28QPG4+4P7", "7P28QPG4+4P8"])

Source code in vgrid/conversion/dggs2geo/olc2geo.py

def olc2geojson(olc_ids):
    """
    Convert OLC (Open Location Code) cell IDs to GeoJSON FeatureCollection.

    Accepts a single olc_id (string) or a list of olc_ids. For each valid OLC cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    olc_ids : str or list of str
        OLC cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "7P28QPG4+4P7"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid OLC cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the OLC cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> olc2geojson("7P28QPG4+4P7")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> olc2geojson(["7P28QPG4+4P7", "7P28QPG4+4P8"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(olc_ids, str):
        olc_ids = [olc_ids]
    olc_features = []
    for olc_id in olc_ids:
        try:
            cell_polygon = olc2geo(olc_id)
            coord = olc.decode(olc_id)
            resolution = coord.codeLength
            olc_feature = graticule_dggs_to_feature(
                "olc", olc_id, resolution, cell_polygon
            )
            olc_features.append(olc_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": olc_features}

olc2geojson_cli()

Command-line interface for olc2geojson supporting multiple OLC codes.

Source code in vgrid/conversion/dggs2geo/olc2geo.py

def olc2geojson_cli():
    """
    Command-line interface for olc2geojson supporting multiple OLC codes.
    """
    parser = argparse.ArgumentParser(
        description="Convert OLC/ Google Plus Codes to GeoJSON"
    )
    parser.add_argument(
        "olc",
        nargs="+",
        help="Input OLC(s), e.g., olc2geojson 7P28QPG4+4P7 7P28QPG4+4P8",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(olc2geojson(args.olc))
    print(geojson_data)

Geohash to Geometry Module

This module provides functionality to convert Geohash cell identifiers to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

geohash2geo(geohash_ids)

Convert Geohash cell IDs to Shapely geometry objects.

Accepts a single geohash_id (string) or a list of geohash_ids. For each valid Geohash cell ID, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

geohash_ids : str or list of str Geohash cell ID(s) to convert. Can be a single string or a list of strings. Example format: "w3gvk1td8"

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single Geohash cell ID is provided, returns a single Shapely Polygon object. If a list of IDs is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding Geohash cell.

Examples

geohash2geo("w3gvk1td8")

geohash2geo(["w3gvk1td8", "w3gvk1td9"]) [, ]

Source code in vgrid/conversion/dggs2geo/geohash2geo.py

def geohash2geo(geohash_ids):
    """
    Convert Geohash cell IDs to Shapely geometry objects.

    Accepts a single geohash_id (string) or a list of geohash_ids. For each valid Geohash cell ID,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    geohash_ids : str or list of str
        Geohash cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "w3gvk1td8"

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single Geohash cell ID is provided, returns a single Shapely Polygon object.
        If a list of IDs is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding Geohash cell.

    Examples
    --------
    >>> geohash2geo("w3gvk1td8")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> geohash2geo(["w3gvk1td8", "w3gvk1td9"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(geohash_ids, str):
        geohash_ids = [geohash_ids]
    geohash_polygons = []
    for geohash_id in geohash_ids:
        try:
            bbox = geohash.bbox(geohash_id)
            min_lat, min_lon = bbox["s"], bbox["w"]
            max_lat, max_lon = bbox["n"], bbox["e"]
            cell_polygon = Polygon(
                [
                    [min_lon, min_lat],
                    [max_lon, min_lat],
                    [max_lon, max_lat],
                    [min_lon, max_lat],
                    [min_lon, min_lat],
                ]
            )
            geohash_polygons.append(cell_polygon)
        except Exception:
            continue
    if len(geohash_polygons) == 1:
        return geohash_polygons[0]
    return geohash_polygons

geohash2geo_cli()

Command-line interface for geohash2geo supporting multiple Geohash cell IDs.

Source code in vgrid/conversion/dggs2geo/geohash2geo.py

def geohash2geo_cli():
    """
    Command-line interface for geohash2geo supporting multiple Geohash cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert Geohash cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "geohash",
        nargs="+",
        help="Input Geohash cell ID(s), e.g., geohash2geo w3gvk1td8 ...",
    )
    args = parser.parse_args()
    polys = geohash2geo(args.geohash)
    return polys

geohash2geojson(geohash_ids)

Convert Geohash cell IDs to GeoJSON FeatureCollection.

Accepts a single geohash_id (string) or a list of geohash_ids. For each valid Geohash cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

geohash_ids : str or list of str Geohash cell ID(s) to convert. Can be a single string or a list of strings. Example format: "w3gvk1td8"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid Geohash cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the Geohash cell ID, resolution level, and cell metadata

Examples

geohash2geojson("w3gvk1td8")

geohash2geojson(["w3gvk1td8", "w3gvk1td9"])

Source code in vgrid/conversion/dggs2geo/geohash2geo.py

def geohash2geojson(geohash_ids):
    """
    Convert Geohash cell IDs to GeoJSON FeatureCollection.

    Accepts a single geohash_id (string) or a list of geohash_ids. For each valid Geohash cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    geohash_ids : str or list of str
        Geohash cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "w3gvk1td8"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid Geohash cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the Geohash cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> geohash2geojson("w3gvk1td8")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> geohash2geojson(["w3gvk1td8", "w3gvk1td9"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(geohash_ids, str):
        geohash_ids = [geohash_ids]
    geohash_features = []
    for geohash_id in geohash_ids:
        try:
            cell_polygon = geohash2geo(geohash_id)
            resolution = len(geohash_id)
            geohash_feature = graticule_dggs_to_feature(
                "geohash", geohash_id, resolution, cell_polygon
            )
            geohash_features.append(geohash_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": geohash_features}

geohash2geojson_cli()

Command-line interface for geohash2geojson supporting multiple Geohash cell IDs.

Source code in vgrid/conversion/dggs2geo/geohash2geo.py

def geohash2geojson_cli():
    """
    Command-line interface for geohash2geojson supporting multiple Geohash cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert Geohash cell ID(s) to GeoJSON"
    )
    parser.add_argument(
        "geohash",
        nargs="+",
        help="Input Geohash cell ID(s), e.g., geohash2geojson w3gvk1td8 ...",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(geohash2geojson(args.geohash))
    print(geojson_data)

GEOREF to Geometry Module

This module provides functionality to convert GEOREF (World Geographic Reference System) codes to Shapely Polygons and GeoJSON FeatureCollection. GEOREF is a standardized system for identifying locations on the Earth's surface using a grid-based coordinate system.

Key Functions

georef2geo(georef_ids)

Convert GEOREF codes to Shapely geometry objects.

Accepts a single georef_id (string) or a list of georef_ids. For each valid GEOREF code, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

georef_ids : str or list of str GEOREF code(s) to convert. Can be a single string or a list of strings. Example format: "VGBL42404651"

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single GEOREF code is provided, returns a single Shapely Polygon object. If a list of codes is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding GEOREF cell.

Examples

georef2geo("VGBL42404651")

georef2geo(["VGBL42404651", "VGBL42404652"]) [, ]

Source code in vgrid/conversion/dggs2geo/georef2geo.py

def georef2geo(georef_ids):
    """
    Convert GEOREF codes to Shapely geometry objects.

    Accepts a single georef_id (string) or a list of georef_ids. For each valid GEOREF code,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    georef_ids : str or list of str
        GEOREF code(s) to convert. Can be a single string or a list of strings.
        Example format: "VGBL42404651"

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single GEOREF code is provided, returns a single Shapely Polygon object.
        If a list of codes is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding GEOREF cell.

    Examples
    --------
    >>> georef2geo("VGBL42404651")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> georef2geo(["VGBL42404651", "VGBL42404652"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(georef_ids, str):
        georef_ids = [georef_ids]
    georef_polygons = []
    for georef_id in georef_ids:
        try:
            _, _, min_lat, min_lon, max_lat, max_lon, _ = georef.georefcell(georef_id)
            cell_polygon = Polygon(
                [
                    [min_lon, min_lat],
                    [max_lon, min_lat],
                    [max_lon, max_lat],
                    [min_lon, max_lat],
                    [min_lon, min_lat],
                ]
            )
            georef_polygons.append(cell_polygon)
        except Exception:
            continue
    if len(georef_polygons) == 1:
        return georef_polygons[0]
    return georef_polygons

georef2geo_cli()

Command-line interface for georef2geo supporting multiple GEOREF codes.

Source code in vgrid/conversion/dggs2geo/georef2geo.py

def georef2geo_cli():
    """
    Command-line interface for georef2geo supporting multiple GEOREF codes.
    """
    parser = argparse.ArgumentParser(
        description="Convert GEOREF code(s) to Shapely Polygons"
    )
    parser.add_argument(
        "georef",
        nargs="+",
        help="Input GEOREF code(s), e.g., georef2geo VGBL42404651 ...",
    )
    args = parser.parse_args()
    polys = georef2geo(args.georef)
    return polys

georef2geojson(georef_ids)

Convert GEOREF codes to GeoJSON FeatureCollection.

Accepts a single georef_id (string) or a list of georef_ids. For each valid GEOREF code, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

georef_ids : str or list of str GEOREF code(s) to convert. Can be a single string or a list of strings. Example format: "VGBL42404651"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid GEOREF cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the GEOREF code, resolution level, and cell metadata

Examples

georef2geojson("VGBL42404651")

georef2geojson(["VGBL42404651", "VGBL42404652"])

Source code in vgrid/conversion/dggs2geo/georef2geo.py

def georef2geojson(georef_ids):
    """
    Convert GEOREF codes to GeoJSON FeatureCollection.

    Accepts a single georef_id (string) or a list of georef_ids. For each valid GEOREF code,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    georef_ids : str or list of str
        GEOREF code(s) to convert. Can be a single string or a list of strings.
        Example format: "VGBL42404651"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid GEOREF cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the GEOREF code, resolution level, and cell metadata

    Examples
    --------
    >>> georef2geojson("VGBL42404651")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> georef2geojson(["VGBL42404651", "VGBL42404652"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(georef_ids, str):
        georef_ids = [georef_ids]
    georef_features = []
    for georef_id in georef_ids:
        try:
            _, _, min_lat, min_lon, max_lat, max_lon, resolution = georef.georefcell(
                georef_id
            )
            cell_polygon = Polygon(
                [
                    [min_lon, min_lat],
                    [max_lon, min_lat],
                    [max_lon, max_lat],
                    [min_lon, max_lat],
                    [min_lon, min_lat],
                ]
            )
            georef_feature = graticule_dggs_to_feature(
                "georef", georef_id, resolution, cell_polygon
            )
            georef_features.append(georef_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": georef_features}

georef2geojson_cli()

Command-line interface for georef2geojson supporting multiple GEOREF codes.

Source code in vgrid/conversion/dggs2geo/georef2geo.py

def georef2geojson_cli():
    """
    Command-line interface for georef2geojson supporting multiple GEOREF codes.
    """
    parser = argparse.ArgumentParser(description="Convert GEOREF code(s) to GeoJSON")
    parser.add_argument(
        "georef",
        nargs="+",
        help="Input GEOREF code(s), e.g., georef2geojson VGBL42404651 ...",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(georef2geojson(args.georef))
    print(geojson_data)

MGRS to Geometry Module

This module provides functionality to convert MGRS (Military Grid Reference System) cell IDs to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

mgrs2geo(mgrs_ids)

Convert MGRS cell IDs to Shapely geometry objects.

Accepts a single mgrs_id (string) or a list of mgrs_ids. For each valid MGRS cell ID, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

mgrs_ids : str or list of str MGRS cell ID(s) to convert. Can be a single string or a list of strings. Example format: "48PXS866916"

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single MGRS cell ID is provided, returns a single Shapely Polygon object. If a list of IDs is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding MGRS cell.

Examples

mgrs2geo("48PXS866916")

mgrs2geo(["48PXS866916", "48PXS866917"]) [, ]

Source code in vgrid/conversion/dggs2geo/mgrs2geo.py

def mgrs2geo(mgrs_ids):
    """
    Convert MGRS cell IDs to Shapely geometry objects.

    Accepts a single mgrs_id (string) or a list of mgrs_ids. For each valid MGRS cell ID,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    mgrs_ids : str or list of str
        MGRS cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "48PXS866916"

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single MGRS cell ID is provided, returns a single Shapely Polygon object.
        If a list of IDs is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding MGRS cell.

    Examples
    --------
    >>> mgrs2geo("48PXS866916")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> mgrs2geo(["48PXS866916", "48PXS866917"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(mgrs_ids, str):
        mgrs_ids = [mgrs_ids]
    mgrs_polygons = []
    for mgrs_id in mgrs_ids:
        try:
            min_lat, min_lon, max_lat, max_lon, resolution = mgrs.mgrscell(mgrs_id)
            cell_polygon = Polygon(
                [
                    (min_lon, min_lat),
                    (max_lon, min_lat),
                    (max_lon, max_lat),
                    (min_lon, max_lat),
                    (min_lon, min_lat),
                ]
            )
            try:
                gzd_json_path = os.path.join(
                    os.path.dirname(__file__), "../generator/gzd.geojson"
                )
                with open(gzd_json_path, "r", encoding="utf-8") as f:
                    gzd_data = json.load(f)
                gzd_features = gzd_data["features"]
                gzd_feature = [
                    feature
                    for feature in gzd_features
                    if feature["properties"].get("gzd") == mgrs_id[:3]
                ][0]
                gzd_geom = shape(gzd_feature["geometry"])
                if mgrs_id[2] not in {"A", "B", "Y", "Z"}:
                    if cell_polygon.intersects(gzd_geom) and not gzd_geom.contains(
                        cell_polygon
                    ):
                        intersected_polygon = cell_polygon.intersection(gzd_geom)
                        if intersected_polygon:
                            cell_polygon = intersected_polygon
            except Exception:
                pass
            mgrs_polygons.append(cell_polygon)
        except Exception:
            continue
    if len(mgrs_polygons) == 1:
        return mgrs_polygons[0]
    return mgrs_polygons

mgrs2geo_cli()

Command-line interface for mgrs2geo supporting multiple MGRS cell IDs.

Source code in vgrid/conversion/dggs2geo/mgrs2geo.py

def mgrs2geo_cli():
    """
    Command-line interface for mgrs2geo supporting multiple MGRS cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert MGRS cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "mgrs",
        nargs="+",
        help="Input MGRS cell ID(s), e.g., mgrs2geo 48PXS866916 ...",
    )
    args = parser.parse_args()
    polys = mgrs2geo(args.mgrs)
    return polys

mgrs2geojson(mgrs_ids)

Convert MGRS cell IDs to GeoJSON FeatureCollection.

Accepts a single mgrs_id (string) or a list of mgrs_ids. For each valid MGRS cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

mgrs_ids : str or list of str MGRS cell ID(s) to convert. Can be a single string or a list of strings. Example format: "48PXS866916"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid MGRS cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the MGRS cell ID, resolution level, and cell metadata

Examples

mgrs2geojson("48PXS866916")

mgrs2geojson(["48PXS866916", "48PXS866917"])

Source code in vgrid/conversion/dggs2geo/mgrs2geo.py

def mgrs2geojson(mgrs_ids):
    """
    Convert MGRS cell IDs to GeoJSON FeatureCollection.

    Accepts a single mgrs_id (string) or a list of mgrs_ids. For each valid MGRS cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    mgrs_ids : str or list of str
        MGRS cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "48PXS866916"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid MGRS cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the MGRS cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> mgrs2geojson("48PXS866916")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> mgrs2geojson(["48PXS866916", "48PXS866917"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(mgrs_ids, str):
        mgrs_ids = [mgrs_ids]
    mgrs_features = []
    for mgrs_id in mgrs_ids:
        try:
            min_lat, min_lon, max_lat, max_lon, resolution = mgrs.mgrscell(mgrs_id)
            cell_polygon = Polygon(
                [
                    (min_lon, min_lat),
                    (max_lon, min_lat),
                    (max_lon, max_lat),
                    (min_lon, max_lat),
                    (min_lon, min_lat),
                ]
            )
            mgrs_feature = graticule_dggs_to_feature(
                "mgrs", mgrs_id, resolution, cell_polygon
            )
            try:
                gzd_json_path = os.path.join(
                    os.path.dirname(__file__), "../generator/gzd.geojson"
                )
                with open(gzd_json_path, "r", encoding="utf-8") as f:
                    gzd_data = json.load(f)
                gzd_features = gzd_data["features"]
                gzd_feature = [
                    feature
                    for feature in gzd_features
                    if feature["properties"].get("gzd") == mgrs_id[:3]
                ][0]
                gzd_geom = shape(gzd_feature["geometry"])
                if mgrs_id[2] not in {"A", "B", "Y", "Z"}:
                    if cell_polygon.intersects(gzd_geom) and not gzd_geom.contains(
                        cell_polygon
                    ):
                        intersected_polygon = cell_polygon.intersection(gzd_geom)
                        if intersected_polygon:
                            mgrs_feature = graticule_dggs_to_feature(
                                "mgrs", mgrs_id, resolution, intersected_polygon
                            )
            except Exception:
                pass
            mgrs_features.append(mgrs_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": mgrs_features}

mgrs2geojson_cli()

Command-line interface for mgrs2geojson supporting multiple MGRS cell IDs.

Source code in vgrid/conversion/dggs2geo/mgrs2geo.py

def mgrs2geojson_cli():
    """
    Command-line interface for mgrs2geojson supporting multiple MGRS cell IDs.
    """
    parser = argparse.ArgumentParser(description="Convert MGRS cell ID(s) to GeoJSON")
    parser.add_argument(
        "mgrs",
        nargs="+",
        help="Input MGRS cell ID(s), e.g., mgrs2geojson 48PXS866916 ...",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(mgrs2geojson(args.mgrs))
    print(geojson_data)

Tilecode to Geometry Module

This module provides functionality to convert Tilecode identifiers to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

tilecode2geo(tilecode_ids)

Convert Tilecode cell IDs to Shapely geometry objects.

Accepts a single tilecode_id (string) or a list of tilecode_ids. For each valid Tilecode cell ID, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

tilecode_ids : str or list of str Tilecode cell ID(s) to convert. Can be a single string or a list of strings. Format: 'z{x}x{y}y{z}' where z is zoom level and x,y are tile coordinates. Example format: "z0x0y0"

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single Tilecode cell ID is provided, returns a single Shapely Polygon object. If a list of IDs is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding Tilecode cell.

Examples

tilecode2geo("z0x0y0")

tilecode2geo(["z0x0y0", "z1x1y1"]) [, ]

Source code in vgrid/conversion/dggs2geo/tilecode2geo.py

def tilecode2geo(tilecode_ids):
    """
    Convert Tilecode cell IDs to Shapely geometry objects.

    Accepts a single tilecode_id (string) or a list of tilecode_ids. For each valid Tilecode cell ID,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    tilecode_ids : str or list of str
        Tilecode cell ID(s) to convert. Can be a single string or a list of strings.
        Format: 'z{x}x{y}y{z}' where z is zoom level and x,y are tile coordinates.
        Example format: "z0x0y0"

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single Tilecode cell ID is provided, returns a single Shapely Polygon object.
        If a list of IDs is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding Tilecode cell.

    Examples
    --------
    >>> tilecode2geo("z0x0y0")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> tilecode2geo(["z0x0y0", "z1x1y1"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(tilecode_ids, str):
        tilecode_ids = [tilecode_ids]
    tilecode_polygons = []
    for tilecode_id in tilecode_ids:
        try:
            match = re.match(r"z(\d+)x(\d+)y(\d+)", tilecode_id)
            if not match:
                continue
            z = int(match.group(1))
            x = int(match.group(2))
            y = int(match.group(3))
            bounds = mercantile.bounds(x, y, z)
            min_lat, min_lon = bounds.south, bounds.west
            max_lat, max_lon = bounds.north, bounds.east
            cell_polygon = Polygon(
                [
                    [min_lon, min_lat],
                    [max_lon, min_lat],
                    [max_lon, max_lat],
                    [min_lon, max_lat],
                    [min_lon, min_lat],
                ]
            )
            tilecode_polygons.append(cell_polygon)
        except Exception:
            continue
    if len(tilecode_polygons) == 1:
        return tilecode_polygons[0]
    return tilecode_polygons

tilecode2geo_cli()

Command-line interface for tilecode2geo supporting multiple Tilecodes.

Source code in vgrid/conversion/dggs2geo/tilecode2geo.py

def tilecode2geo_cli():
    """
    Command-line interface for tilecode2geo supporting multiple Tilecodes.
    """
    parser = argparse.ArgumentParser(
        description="Convert Tilecode(s) to Shapely Polygons"
    )
    parser.add_argument(
        "tilecode_id", nargs="+", help="Input Tilecode(s), e.g. z0x0y0 z1x1y1"
    )
    args = parser.parse_args()
    polys = tilecode2geo(args.tilecode_id)
    return polys

tilecode2geojson(tilecode_ids)

Convert Tilecode cell IDs to GeoJSON FeatureCollection.

Accepts a single tilecode_id (string) or a list of tilecode_ids. For each valid Tilecode cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

tilecode_ids : str or list of str Tilecode cell ID(s) to convert. Can be a single string or a list of strings. Format: 'z{x}x{y}y{z}' where z is zoom level and x,y are tile coordinates. Example format: "z0x0y0"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid Tilecode cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the Tilecode cell ID, resolution level, and cell metadata

Examples

tilecode2geojson("z0x0y0")

tilecode2geojson(["z0x0y0", "z1x1y1"])

Source code in vgrid/conversion/dggs2geo/tilecode2geo.py

def tilecode2geojson(tilecode_ids):
    """
    Convert Tilecode cell IDs to GeoJSON FeatureCollection.

    Accepts a single tilecode_id (string) or a list of tilecode_ids. For each valid Tilecode cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    tilecode_ids : str or list of str
        Tilecode cell ID(s) to convert. Can be a single string or a list of strings.
        Format: 'z{x}x{y}y{z}' where z is zoom level and x,y are tile coordinates.
        Example format: "z0x0y0"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid Tilecode cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the Tilecode cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> tilecode2geojson("z0x0y0")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> tilecode2geojson(["z0x0y0", "z1x1y1"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(tilecode_ids, str):
        tilecode_ids = [tilecode_ids]
    tilecode_features = []
    for tilecode_id in tilecode_ids:
        try:
            match = re.match(r"z(\d+)x(\d+)y(\d+)", tilecode_id)
            if not match:
                continue
            z = int(match.group(1))
            x = int(match.group(2))
            y = int(match.group(3))
            bounds = mercantile.bounds(x, y, z)
            cell_polygon = tilecode2geo(tilecode_id)
            if bounds:
                min_lat, min_lon = bounds.south, bounds.west
                max_lat, max_lon = bounds.north, bounds.east
                cell_polygon = Polygon(
                    [
                        [min_lon, min_lat],
                        [max_lon, min_lat],
                        [max_lon, max_lat],
                        [min_lon, max_lat],
                        [min_lon, min_lat],
                    ]
                )
                resolution = z
                tilecode_feature = graticule_dggs_to_feature(
                    "tilecode_id", tilecode_id, resolution, cell_polygon
                )
                tilecode_features.append(tilecode_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": tilecode_features}

tilecode2geojson_cli()

Command-line interface for tilecode2geojson supporting multiple Tilecodes.

Source code in vgrid/conversion/dggs2geo/tilecode2geo.py

def tilecode2geojson_cli():
    """
    Command-line interface for tilecode2geojson supporting multiple Tilecodes.
    """
    parser = argparse.ArgumentParser(description="Convert Tilecode(s) to GeoJSON")
    parser.add_argument(
        "tilecode_id", nargs="+", help="Input Tilecode(s), e.g. z0x0y0 z1x1y1"
    )
    args = parser.parse_args()
    geojson_data = json.dumps(tilecode2geojson(args.tilecode_id))
    print(geojson_data)

Quadkey to Geometry Module

This module provides functionality to convert Quadkey identifiers to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

quadkey2geo(quadkey_ids)

Convert Quadkey cell IDs to Shapely geometry objects.

Accepts a single quadkey_id (string) or a list of quadkey_ids. For each valid Quadkey cell ID, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

quadkey_ids : str or list of str Quadkey cell ID(s) to convert. Can be a single string or a list of strings. Example format: "13223011131020220011133"

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single Quadkey cell ID is provided, returns a single Shapely Polygon object. If a list of IDs is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding Quadkey cell.

Examples

quadkey2geo("13223011131020220011133")

quadkey2geo(["13223011131020220011133", "13223011131020220011134"]) [, ]

Source code in vgrid/conversion/dggs2geo/quadkey2geo.py

def quadkey2geo(quadkey_ids):
    """
    Convert Quadkey cell IDs to Shapely geometry objects.

    Accepts a single quadkey_id (string) or a list of quadkey_ids. For each valid Quadkey cell ID,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    quadkey_ids : str or list of str
        Quadkey cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "13223011131020220011133"

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single Quadkey cell ID is provided, returns a single Shapely Polygon object.
        If a list of IDs is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding Quadkey cell.

    Examples
    --------
    >>> quadkey2geo("13223011131020220011133")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> quadkey2geo(["13223011131020220011133", "13223011131020220011134"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(quadkey_ids, str):
        quadkey_ids = [quadkey_ids]
    quadkey_polygons = []
    for quadkey_id in quadkey_ids:
        try:
            tile = mercantile.quadkey_to_tile(quadkey_id)
            z = tile.z
            x = tile.x
            y = tile.y
            bounds = mercantile.bounds(x, y, z)
            min_lat, min_lon = bounds.south, bounds.west
            max_lat, max_lon = bounds.north, bounds.east
            cell_polygon = Polygon(
                [
                    [min_lon, min_lat],
                    [max_lon, min_lat],
                    [max_lon, max_lat],
                    [min_lon, max_lat],
                    [min_lon, min_lat],
                ]
            )
            quadkey_polygons.append(cell_polygon)
        except Exception:
            continue
    if len(quadkey_polygons) == 1:
        return quadkey_polygons[0]
    return quadkey_polygons

quadkey2geo_cli()

Command-line interface for quadkey2geo supporting multiple Quadkeys.

Source code in vgrid/conversion/dggs2geo/quadkey2geo.py

def quadkey2geo_cli():
    """
    Command-line interface for quadkey2geo supporting multiple Quadkeys.
    """
    parser = argparse.ArgumentParser(
        description="Convert Quadkey(s) to Shapely Polygons"
    )
    parser.add_argument(
        "quadkey", nargs="+", help="Input Quadkey(s), e.g. 13223011131020220011133 ..."
    )
    args = parser.parse_args()
    polys = quadkey2geo(args.quadkey)
    return polys

quadkey2geojson(quadkey_ids)

Convert Quadkey cell IDs to GeoJSON FeatureCollection.

Accepts a single quadkey_id (string) or a list of quadkey_ids. For each valid Quadkey cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

quadkey_ids : str or list of str Quadkey cell ID(s) to convert. Can be a single string or a list of strings. Example format: "13223011131020220011133"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid Quadkey cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the Quadkey cell ID, resolution level, and cell metadata

Examples

quadkey2geojson("13223011131020220011133")

quadkey2geojson(["13223011131020220011133", "13223011131020220011134"])

Source code in vgrid/conversion/dggs2geo/quadkey2geo.py

def quadkey2geojson(quadkey_ids):
    """
    Convert Quadkey cell IDs to GeoJSON FeatureCollection.

    Accepts a single quadkey_id (string) or a list of quadkey_ids. For each valid Quadkey cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    quadkey_ids : str or list of str
        Quadkey cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "13223011131020220011133"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid Quadkey cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the Quadkey cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> quadkey2geojson("13223011131020220011133")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> quadkey2geojson(["13223011131020220011133", "13223011131020220011134"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(quadkey_ids, str):
        quadkey_ids = [quadkey_ids]
    quadkey_features = []
    for quadkey_id in quadkey_ids:
        try:
            tile = mercantile.quadkey_to_tile(quadkey_id)
            z = tile.z
            x = tile.x
            y = tile.y
            bounds = mercantile.bounds(x, y, z)
            if bounds:
                min_lat, min_lon = bounds.south, bounds.west
                max_lat, max_lon = bounds.north, bounds.east
                cell_polygon = Polygon(
                    [
                        [min_lon, min_lat],
                        [max_lon, min_lat],
                        [max_lon, max_lat],
                        [min_lon, max_lat],
                        [min_lon, min_lat],
                    ]
                )
                resolution = z
                quadkey_feature = graticule_dggs_to_feature(
                    "quadkey", quadkey_id, resolution, cell_polygon
                )
                quadkey_features.append(quadkey_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": quadkey_features}

quadkey2geojson_cli()

Command-line interface for quadkey2geojson supporting multiple Quadkeys.

Source code in vgrid/conversion/dggs2geo/quadkey2geo.py

def quadkey2geojson_cli():
    """
    Command-line interface for quadkey2geojson supporting multiple Quadkeys.
    """
    parser = argparse.ArgumentParser(description="Convert Quadkey(s) to GeoJSON")
    parser.add_argument(
        "quadkey", nargs="+", help="Input Quadkey(s), e.g. 13223011131020220011133 ..."
    )
    args = parser.parse_args()
    geojson_data = json.dumps(quadkey2geojson(args.quadkey))
    print(geojson_data)

Maidenhead to Geometry Module

This module provides functionality to convert Maidenhead locator grid cell IDs to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

maidenhead2geo(maidenhead_ids)

Convert Maidenhead cell IDs to Shapely geometry objects.

Accepts a single maidenhead_id (string) or a list of maidenhead_ids. For each valid Maidenhead cell ID, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

maidenhead_ids : str or list of str Maidenhead cell ID(s) to convert. Can be a single string or a list of strings. Example format: "OK3046."

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single Maidenhead cell ID is provided, returns a single Shapely Polygon object. If a list of IDs is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding Maidenhead cell.

Examples

maidenhead2geo("OK3046.")

maidenhead2geo(["OK3046.", "OK3047."]) [, ]

Source code in vgrid/conversion/dggs2geo/maidenhead2geo.py

def maidenhead2geo(maidenhead_ids):
    """
    Convert Maidenhead cell IDs to Shapely geometry objects.

    Accepts a single maidenhead_id (string) or a list of maidenhead_ids. For each valid Maidenhead cell ID,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    maidenhead_ids : str or list of str
        Maidenhead cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "OK3046."

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single Maidenhead cell ID is provided, returns a single Shapely Polygon object.
        If a list of IDs is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding Maidenhead cell.

    Examples
    --------
    >>> maidenhead2geo("OK3046.")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> maidenhead2geo(["OK3046.", "OK3047."])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(maidenhead_ids, str):
        maidenhead_ids = [maidenhead_ids]
    maidenhead_polygons = []
    for maidenhead_id in maidenhead_ids:
        try:
            _, _, min_lat, min_lon, max_lat, max_lon, _ = maidenhead.maidenGrid(
                maidenhead_id
            )
            cell_polygon = Polygon(
                [
                    [min_lon, min_lat],
                    [max_lon, min_lat],
                    [max_lon, max_lat],
                    [min_lon, max_lat],
                    [min_lon, min_lat],
                ]
            )
            maidenhead_polygons.append(cell_polygon)
        except Exception:
            continue
    if len(maidenhead_polygons) == 1:
        return maidenhead_polygons[0]
    return maidenhead_polygons

maidenhead2geo_cli()

Command-line interface for maidenhead2geo supporting multiple Maidenhead cell IDs.

Source code in vgrid/conversion/dggs2geo/maidenhead2geo.py

def maidenhead2geo_cli():
    """
    Command-line interface for maidenhead2geo supporting multiple Maidenhead cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert Maidenhead cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "maidenhead",
        nargs="+",
        help="Input Maidenhead cell ID(s), e.g., maidenhead2geo OK3046.",
    )
    args = parser.parse_args()
    polys = maidenhead2geo(args.maidenhead)
    return polys

maidenhead2geojson(maidenhead_ids)

Convert Maidenhead cell IDs to GeoJSON FeatureCollection.

Accepts a single maidenhead_id (string) or a list of maidenhead_ids. For each valid Maidenhead cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

maidenhead_ids : str or list of str Maidenhead cell ID(s) to convert. Can be a single string or a list of strings. Example format: "OK3046."

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid Maidenhead cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the Maidenhead cell ID, resolution level, and cell metadata

Examples

maidenhead2geojson("OK3046.")

maidenhead2geojson(["OK3046.", "OK3047."])

Source code in vgrid/conversion/dggs2geo/maidenhead2geo.py

def maidenhead2geojson(maidenhead_ids):
    """
    Convert Maidenhead cell IDs to GeoJSON FeatureCollection.

    Accepts a single maidenhead_id (string) or a list of maidenhead_ids. For each valid Maidenhead cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    maidenhead_ids : str or list of str
        Maidenhead cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "OK3046."

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid Maidenhead cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the Maidenhead cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> maidenhead2geojson("OK3046.")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> maidenhead2geojson(["OK3046.", "OK3047."])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(maidenhead_ids, str):
        maidenhead_ids = [maidenhead_ids]
    maidenhead_features = []
    for maidenhead_id in maidenhead_ids:
        try:
            cell_polygon = maidenhead2geo(maidenhead_id)
            resolution = int(len(maidenhead_id) / 2)
            maidenhead_feature = graticule_dggs_to_feature(
                "maidenhead", maidenhead_id, resolution, cell_polygon
            )
            maidenhead_features.append(maidenhead_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": maidenhead_features}

maidenhead2geojson_cli()

Command-line interface for maidenhead2geojson supporting multiple Maidenhead cell IDs.

Source code in vgrid/conversion/dggs2geo/maidenhead2geo.py

def maidenhead2geojson_cli():
    """
    Command-line interface for maidenhead2geojson supporting multiple Maidenhead cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert Maidenhead cell ID(s) to GeoJSON"
    )
    parser.add_argument(
        "maidenhead",
        nargs="+",
        help="Input Maidenhead cell ID(s), e.g., maidenhead2geojson OK3046.",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(maidenhead2geojson(args.maidenhead))
    print(geojson_data)

GARS to Geometry Module

This module provides functionality to convert GARS (Global Area Reference System) cell IDs to Shapely Polygons and GeoJSON FeatureCollection.

Key Functions

gars2geo(gars_ids)

Convert GARS cell IDs to Shapely geometry objects.

Accepts a single gars_id (string) or a list of gars_ids. For each valid GARS cell ID, creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

gars_ids : str or list of str GARS cell ID(s) to convert. Can be a single string or a list of strings. Example format: "574JK1918"

Returns

shapely.geometry.Polygon or list of shapely.geometry.Polygon If a single GARS cell ID is provided, returns a single Shapely Polygon object. If a list of IDs is provided, returns a list of Shapely Polygon objects. Each polygon represents the boundaries of the corresponding GARS cell.

Examples

gars2geo("574JK1918")

gars2geo(["574JK1918", "574JK1919"]) [, ]

Source code in vgrid/conversion/dggs2geo/gars2geo.py

def gars2geo(gars_ids):
    """
    Convert GARS cell IDs to Shapely geometry objects.

    Accepts a single gars_id (string) or a list of gars_ids. For each valid GARS cell ID,
    creates a Shapely Polygon representing the grid cell boundaries. Skips invalid or
    error-prone cells.

    Parameters
    ----------
    gars_ids : str or list of str
        GARS cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "574JK1918"

    Returns
    -------
    shapely.geometry.Polygon or list of shapely.geometry.Polygon
        If a single GARS cell ID is provided, returns a single Shapely Polygon object.
        If a list of IDs is provided, returns a list of Shapely Polygon objects.
        Each polygon represents the boundaries of the corresponding GARS cell.

    Examples
    --------
    >>> gars2geo("574JK1918")
    <shapely.geometry.polygon.Polygon object at ...>

    >>> gars2geo(["574JK1918", "574JK1919"])
    [<shapely.geometry.polygon.Polygon object at ...>, <shapely.geometry.polygon.Polygon object at ...>]
    """
    if isinstance(gars_ids, str):
        gars_ids = [gars_ids]
    gars_polygons = []
    for gars_id in gars_ids:
        try:
            gars_grid = garsgrid.GARSGrid(gars_id)
            wkt_polygon = gars_grid.polygon
            cell_polygon = Polygon(list(wkt_polygon.exterior.coords))
            gars_polygons.append(cell_polygon)
        except Exception:
            continue
    if len(gars_polygons) == 1:
        return gars_polygons[0]
    return gars_polygons

gars2geo_cli()

Command-line interface for gars2geo supporting multiple GARS cell IDs.

Source code in vgrid/conversion/dggs2geo/gars2geo.py

def gars2geo_cli():
    """
    Command-line interface for gars2geo supporting multiple GARS cell IDs.
    """
    parser = argparse.ArgumentParser(
        description="Convert GARS cell ID(s) to Shapely Polygons"
    )
    parser.add_argument(
        "gars",
        nargs="+",
        help="Input GARS cell ID(s), e.g., gars2geo 574JK1918 ...",
    )
    args = parser.parse_args()
    polys = gars2geo(args.gars)
    return polys

gars2geojson(gars_ids)

Convert GARS cell IDs to GeoJSON FeatureCollection.

Accepts a single gars_id (string) or a list of gars_ids. For each valid GARS cell ID, creates a GeoJSON feature with polygon geometry representing the grid cell boundaries. Skips invalid or error-prone cells.

Parameters

gars_ids : str or list of str GARS cell ID(s) to convert. Can be a single string or a list of strings. Example format: "574JK1918"

Returns

dict A GeoJSON FeatureCollection containing polygon features for each valid GARS cell. Each feature includes: - geometry: Polygon representing the cell boundaries - properties: Contains the GARS cell ID, resolution level, and cell metadata

Examples

gars2geojson("574JK1918")

gars2geojson(["574JK1918", "574JK1919"])

Source code in vgrid/conversion/dggs2geo/gars2geo.py

def gars2geojson(gars_ids):
    """
    Convert GARS cell IDs to GeoJSON FeatureCollection.

    Accepts a single gars_id (string) or a list of gars_ids. For each valid GARS cell ID,
    creates a GeoJSON feature with polygon geometry representing the grid cell boundaries.
    Skips invalid or error-prone cells.

    Parameters
    ----------
    gars_ids : str or list of str
        GARS cell ID(s) to convert. Can be a single string or a list of strings.
        Example format: "574JK1918"

    Returns
    -------
    dict
        A GeoJSON FeatureCollection containing polygon features for each valid GARS cell.
        Each feature includes:
        - geometry: Polygon representing the cell boundaries
        - properties: Contains the GARS cell ID, resolution level, and cell metadata

    Examples
    --------
    >>> gars2geojson("574JK1918")
    {'type': 'FeatureCollection', 'features': [...]}

    >>> gars2geojson(["574JK1918", "574JK1919"])
    {'type': 'FeatureCollection', 'features': [...]}
    """
    if isinstance(gars_ids, str):
        gars_ids = [gars_ids]
    gars_features = []
    for gars_id in gars_ids:
        try:
            gars_grid = garsgrid.GARSGrid(gars_id)
            wkt_polygon = gars_grid.polygon
            resolution_minute = gars_grid.resolution
            resolution = 1
            if resolution_minute == 30:
                resolution = 1
            elif resolution_minute == 15:
                resolution = 2
            elif resolution_minute == 5:
                resolution = 3
            elif resolution_minute == 1:
                resolution = 4
            cell_polygon = Polygon(list(wkt_polygon.exterior.coords))
            gars_feature = graticule_dggs_to_feature(
                "gars", gars_id, resolution, cell_polygon
            )
            gars_features.append(gars_feature)
        except Exception:
            continue
    return {"type": "FeatureCollection", "features": gars_features}

gars2geojson_cli()

Command-line interface for gars2geojson supporting multiple GARS cell IDs.

Source code in vgrid/conversion/dggs2geo/gars2geo.py

def gars2geojson_cli():
    """
    Command-line interface for gars2geojson supporting multiple GARS cell IDs.
    """
    parser = argparse.ArgumentParser(description="Convert GARS cell ID(s) to GeoJSON")
    parser.add_argument(
        "gars",
        nargs="+",
        help="Input GARS cell ID(s), e.g., gars2geojson 574JK1918 ...",
    )
    args = parser.parse_args()
    geojson_data = json.dumps(gars2geojson(args.gars))
    print(geojson_data)