Source code for satorbis_kit.raster.raster_to_vector

"""
Raster to vector conversion module with OpenEO integration.

Provides functionality to convert raster data to vector format using OpenEO backend.
"""

from typing import Optional
import openeo

from satorbis_kit.constants import Constants




def raster_to_vector(
    raster_s3_path: str,
    output_s3_path: str,
    band: int = 1,
    output_driver: str = "GeoJSON",
    simplify_tolerance: Optional[float] = None,
    job_title: Optional[str] = None,
    wait_for_completion: bool = False,
) -> openeo.rest.job.BatchJob:
    """
    Convert raster data to vector format using OpenEO backend.

    This function takes a raster file (e.g., GeoTIFF) and converts it to a vector
    format (e.g., GeoJSON, GeoPackage) by vectorizing pixel values. It uses the
    OpenEO backend for processing and supports S3 storage for both input and output.

    Args:
        raster_s3_path (str): S3 URI to input raster file.
            Example: "s3://bucket/input.tif"
        output_s3_path (str): S3 URI for output vector file.
            Example: "s3://bucket/output.geojson"
        band (int, optional): Band number to vectorize (1-indexed). Defaults to 1.
        output_driver (str, optional): Output vector format driver.
            Options: "GeoJSON", "GPKG", "GML", "KML". Defaults to "GeoJSON".
        simplify_tolerance (float, optional): Tolerance for geometry simplification.
            If None, no simplification is applied. Defaults to None.
        job_title (str, optional): Custom job title. If None, auto-generated
            from input filename.
        wait_for_completion (bool, optional): If True, blocks until job completes.
            If False, returns immediately after starting. Defaults to False.

    Returns:
        openeo.rest.job.BatchJob: OpenEO batch job object that can be monitored
            and managed. Use job.status() to check status.

    Raises:
        ConnectionError: If unable to connect to OpenEO backend.
        ValueError: If S3 paths are invalid or band number is out of range.

    Examples:
        Basic raster to vector conversion:

        >>> from satorbis_kit.raster import raster_to_vector
        >>> job = raster_to_vector(
        ...     raster_s3_path="s3://satimg-to-be-deleted/Sentinel2/TCX8021/20251201_091002001000000_TCX8021.tif",
        ...     output_s3_path="s3://satsure-products-testing/20251201_091002001000000_TCX8021.geojson"
        ... )
        >>> print(job.status())

        Convert specific band with simplification:

        >>> job = raster_to_vector(
        ...     raster_s3_path="s3://bucket/input.tif",
        ...     output_s3_path="s3://bucket/output.geojson",
        ...     band=2,
        ...     simplify_tolerance=0.001,
        ...     wait_for_completion=True
        ... )
        >>> print(f"Conversion complete: {job.status()}")

        Convert to GeoPackage format:

        >>> job = raster_to_vector(
        ...     raster_s3_path="s3://bucket/input.tif",
        ...     output_s3_path="s3://bucket/output.gpkg",
        ...     output_driver="GPKG",
        ...     job_title="Raster to GeoPackage Conversion"
        ... )

        Using OpenEO directly:

        >>> import openeo
        >>> from satorbis_kit.constants import Constants
        >>> con = openeo.connect(Constants.DEV_URL)
        >>> cube = con.datacube_from_process(
        ...     process_id="raster_to_vector",
        ...     raster_s3_path="s3://bucket/input.tif",
        ...     output_s3_path="s3://bucket/output.geojson",
        ...     band=1,
        ...     output_driver="GeoJSON",
        ...     simplify_tolerance=None
        ... )
        >>> job = cube.create_job(title="Raster to Vector Job")
        >>> job.start_and_wait()

    Note:
        - Requires AWS credentials configured for S3 access
        - OpenEO backend accessible via Constants.DEV_URL
        - Input must be a valid raster file with proper georeferencing
        - Output format determined by output_driver parameter
        - Simplification can significantly reduce output file size
        - Large rasters may take considerable time to vectorize
    """
    # Connect to OpenEO
    con = openeo.connect(
        Constants.DEV_URL,
    )

    # Create datacube from raster to vector process
    cube = con.datacube_from_process(
        process_id="raster_to_vector",
        raster_s3_path=raster_s3_path,
        output_s3_path=output_s3_path,
        band=band,
        output_driver=output_driver,
        simplify_tolerance=simplify_tolerance,
    )

    # Create job with descriptive title
    if job_title is None:
        job_title = f"Raster to Vector Job - {raster_s3_path.split('/')[-1]}"

    job = cube.create_job(title=job_title)

    # Start job and optionally wait
    if wait_for_completion:
        job.start_and_wait()
    else:
        job.start()

    return job