rss_da_stac 0.0.1__py3-none-any.whl

rss_da_stac/__init__.py

@@ -0,0 +1,50 @@
+"""
+rss_da_stac: A Python package for working with Sentinel-2 STAC items across different providers
+"""
+
+# Import all public functions and classes from utils
+from .utils import (
+    CDSE,
+    ELEMENT84,
+    PLANETARYCOMPUTER,
+    ItemNotFoundError,
+    ProductIdParseError,
+    ProviderNotFoundError,
+    S2Scene,
+    # Exceptions
+    S2StacError,
+    StacProvider,
+    change_processing_level,
+    convert_item,
+    extract_stac_item_from_tiff,
+    get_item_by_id,
+    get_provider,
+    parse_cdse_s2_id,
+    qvf_to_stac,
+    stac_to_qvf,
+    read_items
+)
+
+
+# Define what gets imported with "from rss_da_stac import *"
+__all__ = [
+    "StacProvider",
+    "S2Scene",
+    "CDSE", 
+    "ELEMENT84",
+    "PLANETARYCOMPUTER",
+    "parse_cdse_s2_id",
+    "get_provider", 
+    "convert_item",
+    "change_processing_level",
+    "get_item_by_id",
+    "stac_to_qvf",
+    "qvf_to_stac",
+    "extract_stac_item_from_tiff",
+    "read_items",
+    # Exceptions
+    "S2StacError",
+    "ProductIdParseError", 
+    "ProviderNotFoundError",
+    "ItemNotFoundError"
+]

rss_da_stac/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

rss_da_stac/cli.py

@@ -0,0 +1,212 @@
+import json
+import logging
+import sys
+from typing import Optional, List
+
+import typer
+from pystac import Item, ItemCollection, STACTypeError
+
+import rss_da_stac
+
+
+def setup_logging(verbose: int):
+    """Setup logging based on verbosity level."""
+    if verbose == 0:
+        level = logging.WARNING
+    elif verbose == 1:
+        level = logging.INFO
+    else:  # verbose >= 2
+        level = logging.DEBUG
+    
+    logging.basicConfig(
+        level=level,
+        format='%(levelname)s: %(message)s',
+        stream=sys.stderr  # Log to stderr so it doesn't interfere with JSON output to stdout
+    )
+
+
+def read_item(src: Optional[str] = None) -> ItemCollection:
+    """
+    Get JSON data either from file or stdin pipe.
+    Should work for either item or itemcollection
+
+    this is almost a duplicate of rss_da_stac.read_items which
+    might cause confusion
+    """
+    if src:
+        # Read from file
+        try:
+            item = Item.from_file(src)
+            item_coll = ItemCollection(items=[item])
+        except STACTypeError:
+            item_coll = ItemCollection.from_file(src)
+    else:
+        stdin_data = sys.stdin.read()
+        jsondata = json.loads(stdin_data)
+        try:
+            item = Item.from_dict(jsondata)
+            item_coll = ItemCollection(items=[item])
+        except STACTypeError:
+            item_coll = ItemCollection.from_dict(jsondata)
+    return item_coll
+
+app = typer.Typer()
+
+@app.callback()
+def main(
+    verbose: int = typer.Option(0, "-v", "--verbose", count=True, 
+                               help="Increase verbosity. Use -v for info, -vv for debug")
+):
+    """
+    CLI tool for STAC item processing.
+    
+    Use -v for info logging, -vv for debug logging.
+    """
+    setup_logging(verbose)
+
+@app.command()
+def qvf2item(
+    qvfnames: List[str] = typer.Argument(None, help="One or more valid S2 QVF filenames"),
+    file: Optional[str] = typer.Option(None, "--file", "-f", help="File containing QVF filenames (one per line)"),
+    provider: str = typer.Option('element84', '--provider', help="STAC provider: element84, planetary-computer, or CDSE"),
+    level: str = typer.Option('l2a', '--level', help="Processing level (l2a, l2apre, or l1c)"),
+    geom: Optional[str] = typer.Option(None, help="Geometry to help in filtering duplicates"),
+    pretty: bool = typer.Option(False, '--pretty', help="Pretty-print the JSON output")
+):
+    """
+    Convert one or more QVF files to a STAC ItemCollection.
+
+    Args:
+        qvfnames (List[str]): One or more QVF filenames to process (positional arguments).
+        file (Optional[str]): Path to a file containing QVF filenames (one per line).
+        provider (str): The STAC provider (element84, planetary-computer, or CDSE).
+        level (str): The processing level (l2a, l2apre, or l1c).
+        pretty (bool): Whether to pretty-print the JSON output.
+    """
+
+    # Combine filenames from command-line arguments and file (if provided)
+    if qvfnames:
+        filenames = list(qvfnames)  # Start with filenames from command-line arguments
+    else:
+        filenames = []
+    if file:
+        try:
+            with open(file, 'r') as f:
+                file_lines = [line.strip() for line in f if line.strip()]  # Read non-empty lines
+                filenames.extend(file_lines)  # Add filenames from the file
+        except Exception as e:
+            typer.echo(f"Error reading file '{file}': {e}", err=True)
+            raise typer.Exit(1)
+
+    # Ensure at least one filename is provided
+    if not filenames:
+        typer.echo("Error: No QVF filenames provided. Use positional arguments or the --file option.", err=True)
+        raise typer.Exit(1)
+
+    # Map provider to STAC provider constants
+    match provider.lower():
+        case 'element84':
+            stac_prov = rss_da_stac.ELEMENT84
+        case 'copernicus' | 'cdse':
+            stac_prov = rss_da_stac.CDSE
+        case 'planetary-computer' | 'planetary_computer' | 'planetarycomputer':
+            stac_prov = rss_da_stac.PLANETARYCOMPUTER
+        case _:
+            typer.echo(f"Error: provider '{provider}' not recognised. Use 'element84', 'planetary-computer', or 'CDSE'.", err=True)
+            raise typer.Exit(1)
+
+    # Process each QVF file and collect the resulting STAC Items
+    items = []
+    for qvfname in filenames:
+        try:
+            itemcoll = rss_da_stac.qvf_to_stac(qvfname, dst_provider=stac_prov, level=level, geom=geom)
+            items.extend(itemcoll.items)
+        except Exception as e:
+            typer.echo(f"Error processing QVF file '{qvfname}': {e}", err=True)
+            raise typer.Exit(1)
+
+    # Create an ItemCollection from the collected items
+    item_collection = ItemCollection(items=items)
+    output = json.dumps(item_collection.to_dict(), indent=4 if pretty else None)
+    print(output)
+
+
+
+@app.command()
+def item2qvf(json_src: Optional[str] = typer.Argument(None, help="JSON file path"),
+             stage: str = typer.Option("adc", "--stage", help="Stage parameter")):
+    """
+    Given a stac item or itemcollection, provide the equivalent qvf compliant
+    name for each item. Use the option '--stage' to set the output stage
+
+    Example
+
+    rss_da_stac qvf2item cfmsre_t56kkv_20221223_adbm6.tif|s2stac item2qvf  --stage adc
+    
+    """
+    item_coll = read_item(json_src)
+    for item in item_coll.items:
+        qvfname = rss_da_stac.stac_to_qvf(item, stage=stage)
+        print(qvfname)
+
+@app.command()
+def item2item(json_src: Optional[str] = typer.Argument(None, help="JSON file path"),
+             provider: str = typer.Option('element84', '--provider', help="STAC provider: element84 or CDSE")): 
+    """Convert item to item format."""
+    match provider.lower():
+        case 'element84':
+            stac_prov = rss_da_stac.ELEMENT84
+        case 'copernicus':
+            stac_prov = rss_da_stac.CDSE
+        case 'cdse':
+            stac_prov = rss_da_stac.CDSE
+        case _:
+            typer.echo(f"Error: provider '{provider}' not recognised. Use 'element84' or 'CDSE'", err=True)
+            raise typer.Exit(1)
+        
+    item_coll = read_item(json_src)
+    new_items = []
+    for item in item_coll.items:
+        newitem = rss_da_stac.convert_item(item, stac_prov)
+        new_items.append(newitem)
+    new_item_coll = ItemCollection(items=new_items)
+    print(json.dumps(new_item_coll.to_dict()))
+
+
+@app.command()
+def relevel(json_src: Optional[str] = typer.Argument(None, help="JSON file path")):
+    item_coll = read_item(json_src)
+    new_items = []
+    for item in item_coll.items:
+        newitem = rss_da_stac.change_processing_level(item)
+        new_items.append(newitem)
+    new_item_coll = ItemCollection(items=new_items)
+    print(json.dumps(new_item_coll.to_dict()))
+
+
+
+@app.command()
+def histitem(tif_file: str = typer.Argument(..., help="geotiff with item in metadata")):
+    item = rss_da_stac.extract_stac_item_from_tiff(tif_file)
+    print(json.dumps(item.to_dict(transform_hrefs=False)))
+    
+
+@app.command()
+def cat(
+    files: List[str] = typer.Argument(..., help="List of JSON file paths to concatenate")
+):
+    """
+    Concatenate items from a list of files into a single ItemCollection.
+
+    Args:
+        files (List[str]): A list of file paths containing STAC Items or ItemCollections.
+    """
+    all_items = []
+    for fname in files:
+        all_items += read_item(fname).items  # Read items from each file and add to the list
+    icoll = ItemCollection(items=all_items)
+    print(json.dumps(icoll.to_dict()))  # Output the concatenated ItemCollection as JSON
+
+
+if __name__ == "__main__":
+    app()

rss_da_stac/uri2l2a.py

@@ -0,0 +1,177 @@
+"""
+This module aims to provide a way of mapping from an L1C item to an L2A item.
+Turns out that this isn't quite as easy as it sounds, since there can be
+more than one satellite, capture date, tile combinations.
+
+When you get two possible ones, you can't automatically work out which one you want.
+
+For example, if you have an esaid like
+
+S2B_MSIL1C_20250917T003659_N0511_R059_T54KZV_20250917T043259
+
+and you want to find the L2A equivalent, you have to choose between
+S2B_MSIL2A_20250917T003659_N0511_R059_T54KZV_20250917T044524
+
+and 
+
+S2B_MSIL2A_20250917T003659_N0511_R059_T54KZV_20250917T035150
+
+Notice that the product discrimination times don't match the original 
+(20250917T043259). 
+
+The assumption I'm going to make is that the order will be the same. Which
+means you need to find the order of the L1C first, Ie get the candidates
+sortd by product discrimination times:
+
+S2B_MSIL1C_20250917T003659_N0511_R059_T54KZV_20250917T033704
+S2B_MSIL1C_20250917T003659_N0511_R059_T54KZV_20250917T043259
+
+and notice that our match is the _second_ of these. Therefore we
+want the _second_ of the L2A candidates. So we want 
+
+S2B_MSIL2A_20250917T003659_N0511_R059_T54KZV_20250917T044524
+
+maybe there is an easier way.
+
+"""
+import json
+from typing import List, Optional
+from pystac import Item, ItemCollection
+from pystac_client import Client
+import typer 
+from rss_da_stac import StacProvider, get_provider
+from rss_da_stac import ELEMENT84, CDSE
+from rss_da_stac import parse_cdse_s2_id
+
+app = typer.Typer()
+
+
+def filter_by_id(item_coll: ItemCollection, product_uri: str) -> Item:
+    """
+    I'm thinking the reliable way to do this is by checking the order 
+    in which these have been created from the source of origin.
+    so we might need to get both items from copernicus
+
+    Assume product_uri is an l1c style
+
+    we return the index of the matching item assuming we sort
+    by product_disc_time
+
+    we search by the datatake start time. Is that going to be correct?
+
+    """
+    details = parse_cdse_s2_id(product_uri)
+    client = Client.open(ELEMENT84.url)
+    collection = ['sentinel-2-l1c']
+    datestring = details['datatake_start_time'].strftime("%Y-%m-%d")
+    search = client.search(
+        collections=collection,
+        datetime=datestring,
+        query={
+            "grid:code": {"eq": details["grid:code"]}
+        }
+    )
+    coll = search.item_collection()
+    product_disc_times = []
+    product_uris = []
+    for item in coll.items:
+        thisuril = item.properties['s2:product_uri'].replace('.SAFE','')
+        product_uris.append(thisuril)
+        itemdetails = parse_cdse_s2_id(thisuril)
+        product_disc_times.append(itemdetails['product_disc_time'])
+    sorted_uris = [uri for _, uri in sorted(zip(product_disc_times, product_uris))]
+    index = sorted_uris.index(product_uri)
+
+    # now sort our original item_coll 
+    # since l2a for both cdse and element84 include the product_disc_time
+    # in the id then we can just sort the ids
+    ids = [item.id for item in item_coll]
+    # if they are cdse style then use parse
+    if get_provider(item_coll.items[0]) == CDSE:
+        product_disc_times = [parse_cdse_s2_id(id)['product_disc_time'] for id in ids]
+    else:
+        # you need to do it via 
+        product_disc_times = [parse_cdse_s2_id(item.properties['s2:product_uri'])['product_disc_time'] for item in item_coll.items]
+    # sort the item
+    sorted_items = [item for _, item in sorted(zip(product_disc_times, item_coll.items))]
+    return sorted_items[index]
+
+
+
+def product_uri_to_l2a(product_uri: str, dst_provider: StacProvider=ELEMENT84) -> Item:
+    """ 
+    given a product uri, like 'S2B_MSIL1C_20250917T003659_N0511_R059_T54KZV_20250917T043259'
+    get the equivalent as an element84 s2l2a
+    
+    """
+    details = parse_cdse_s2_id(product_uri)
+    level = 'l2a'
+    client = Client.open(dst_provider.url)
+    collection = dst_provider.__getattribute__(level)
+    #datestring = details['product_disc_time'].strftime("%Y-%m-%d")
+    datestring = details['datatake_start_time'].strftime("%Y-%m-%d")
+    search = client.search(
+        collections=[collection],
+        datetime=datestring,
+        query={
+            "grid:code": {"eq": details["grid:code"]}
+        }
+    )
+    coll = search.item_collection()
+    # now filter if needed
+    if len(coll.items) == 1:
+        selitem = coll.items[0]
+        return selitem
+    if len(coll.items) > 1:
+        sel_item = filter_by_id(coll, product_uri)
+        return sel_item
+    return None
+
+
+@app.command()
+def updateproduct(
+    uris: List[str] = typer.Argument(None, help="One or more valid S2 L1C product uris"),
+    file: Optional[str] = typer.Option(None, "--file", "-f", help="File containing S2 L1c product uris (one per line)"),
+    provider: str = typer.Option('element84', '--provider', help="STAC provider: element84, or CDSE"),
+):
+    """
+    given s1c esa ids, convert to s2l2a and change provider to element84
+    
+    """
+    match provider.lower():
+        case 'element84':
+            stac_prov = ELEMENT84
+        case 'copernicus' | 'cdse':
+            stac_prov = CDSE
+        case _:
+            typer.echo(f"Error: provider '{provider}' not recognised. Use 'element84', 'planetary-computer', or 'CDSE'.", err=True)
+            raise typer.Exit(1)
+
+    if uris:
+        product_uris = list(uris)  # Start with filenames from command-line arguments
+    else:
+        product_uris = []
+    if file:
+        try:
+            with open(file, 'r') as f:
+                file_lines = [line.strip() for line in f if line.strip()]  # Read non-empty lines
+                product_uris.extend(file_lines)  # Add filenames from the file
+        except Exception as e:
+            typer.echo(f"Error reading file '{file}': {e}", err=True)
+            raise typer.Exit(1)
+    
+    # Process each product uri file and collect the resulting STAC Items
+    items = []
+    for uri in product_uris:
+        try:
+            item = product_uri_to_l2a(uri, dst_provider=stac_prov)
+            items.append(item)
+        except Exception as e:
+            typer.echo(f"Error processing uri '{uri}': {e}", err=True)
+            raise typer.Exit(1)
+    item_collection = ItemCollection(items=items)
+    output = json.dumps(item_collection.to_dict())
+    print(output)
+
+if __name__ == "__main__":
+    app()

rss_da_stac/utils.py

@@ -0,0 +1,718 @@
+"""
+rss_da_stac: A Python package for working with Sentinel-2 STAC items across different providers
+"""
+
+import base64
+import json
+import logging
+import re
+import xml.etree.ElementTree as ET
+import zlib
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from shapely.geometry import Polygon
+from shapely.geometry import shape, mapping
+
+from typing import Any, Dict, Optional
+from typing import List
+
+import tifftools
+from pystac import Item, ItemCollection, STACTypeError
+from pystac_client import Client
+
+# Set up logging
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class S2Scene:
+    """
+    Represents a Sentinel-2 scene identifier with validation.
+
+    Attributes:
+        s2scene (str): The Sentinel-2 scene identifier.
+
+    Methods:
+        validate_s2scene(value: str) -> str : Class method to validate
+            the s2scene identifier format, ensuring it follows either
+            'tXXYYY' format or the 'MGRS-XXYYY' format.
+
+    
+    Examples:
+        Using positional argument:
+            scene = S2Scene('MGRS-32TNL')
+
+        Using keyword argument:
+            scene = S2Scene(s2scene='t01cdn')
+
+    """
+    s2scene: str
+    def __post_init__(self):
+        value = self.s2scene
+        if value.upper().startswith('MGRS-'):
+            value = value[5:]  # Remove the 'MGRS-' prefix
+            if len(value) == 5 and all(part.isalnum() for part in value):
+                return f't{value.lower()}'
+            else:
+                raise ValueError(f'S2 scene format must be either "tXXYYY" or "MGRS-XXYYY", received: {value}')
+        if len(value) == 6 and value.startswith('t') and all(part.isalnum() for part in value[1:]):
+            return value.lower()
+        else:
+            raise ValueError(f'S2 scene format must be either "tXXYYY" or "MGRS-XXYYY", received: {value}')
+
+    def qvf_style(self):
+        if self.s2scene.upper().startswith('MGRS-'):
+            return f"t{self.s2scene[5:].lower()}"
+        else:
+            return(self.s2scene)
+
+    def mgrs_style(self):
+        if self.s2scene.startswith('t'):
+            return f"MGRS-{self.s2scene[1:].upper()}"
+        else:
+            return(self.s2scene)
+
+
+
+@dataclass
+class StacProvider:
+    """Represents a STAC provider with its endpoints and collection names."""
+    name: str
+    url: str
+    l1c: str 
+    l2a: str
+    l2apre :str
+    l2aold :str
+    mgrs_tile: str 
+
+    def __post_init__(self):
+        """Validate provider configuration."""
+        if not self.url.startswith(('http://', 'https://')):
+            raise ValueError(f"Invalid URL for provider {self.name}: {self.url}")
+
+
+# Provider configurations
+CDSE = StacProvider(
+    'CDSE', 
+    url="https://stac.dataspace.copernicus.eu/v1", 
+    l1c='sentinel-2-l1c', 
+    l2a="sentinel-2-l2a",
+    l2apre="sentinel-2-l2a",
+    l2aold="sentinel-2-l2a",
+    mgrs_tile="grid:code"
+)
+
+ELEMENT84 = StacProvider(
+    'Element84', 
+    url="https://earth-search.aws.element84.com/v1",
+    l1c='sentinel-2-l1c',
+    l2a='sentinel-2-c1-l2a',
+    l2apre='sentinel-2-pre-c1-l2a',
+    l2aold="sentinel-2-l2a",
+    mgrs_tile="grid:code"
+)
+
+
+PLANETARYCOMPUTER = StacProvider(
+    'planetary-computer', 
+    url="https://planetarycomputer.microsoft.com/api/stac/v1/",
+    l1c=None,
+    l2a='sentinel-2-l2a',
+    l2apre=None,
+    l2aold=None,
+    mgrs_tile="s2:mgrs_tile"
+    )
+
+
+#https://planetarycomputer.microsoft.com/api/stac/v1/collections/sentinel-2-l2a
+
+
+class S2StacError(Exception):
+    """Base exception for rss_da_stac operations."""
+    pass
+
+
+class ProductIdParseError(S2StacError):
+    """Raised when a Sentinel-2 product ID cannot be parsed."""
+    pass
+
+
+class ProviderNotFoundError(S2StacError):
+    """Raised when a provider cannot be determined from an item."""
+    pass
+
+
+class ItemNotFoundError(S2StacError):
+    """Raised when an item cannot be found in a STAC catalog."""
+    pass
+
+
+def parse_cdse_s2_id(product_id: str) -> Dict[str, Any]:
+    """
+    Parse Sentinel-2 product ID to extract key metadata.
+    
+    Format: S2A_MSIL1C_20170118T001201_N0204_R073_T55HED_20170118T001250[.SAFE]
+    This is the CDSE format.
+    
+    Args:
+        product_id: Sentinel-2 product identifier
+        
+    Returns:
+        Dictionary containing parsed metadata
+        
+    Raises:
+        ProductIdParseError: If the product ID format is invalid
+    """
+    if not isinstance(product_id, str):
+        raise ProductIdParseError(f"Product ID must be a string, got {type(product_id)}")
+    
+    # Remove .SAFE suffix if present
+    clean_id = product_id.replace('.SAFE', '')
+    
+    # Parse using regex
+    pattern = r'S2([ABC])_(MSIL1C|MSIL2A)_(\d{8}T\d{6})_N\d{4}_R(\d{3})_T(\w{5})_(\d{8}T\d{6})'
+    match = re.match(pattern, clean_id)
+    
+    if not match:
+        raise ProductIdParseError(f"Could not parse product ID: {product_id}")
+    
+    satellite = match.group(1)  # A, B, or C
+    s2level = match.group(2)    # MSIL1C or MSIL2A
+    datatake_start_time = match.group(3)  # 20170118T001201
+    relative_orbit = match.group(4)  # 073
+    tile_id = match.group(5)    # 55HED
+    product_disc_time = match.group(6)
+    # Convert sensing time to datetime
+    try:
+        datatake_start_time = datetime.strptime(datatake_start_time, '%Y%m%dT%H%M%S')
+    except ValueError as e:
+        raise ProductIdParseError(f"Invalid sensing time format in {product_id}: {e}")
+    try:
+        product_disc_time = datetime.strptime(product_disc_time, '%Y%m%dT%H%M%S')
+    except ValueError as e:
+        raise ProductIdParseError(f"Invalid sensing time format in {product_id}: {e}")
+    
+    return {
+        'satellite': satellite,
+        'datatake_start_time': datatake_start_time,
+        's2level': s2level,
+        'relative_orbit': relative_orbit,
+        'grid:code': f"MGRS-{tile_id}",
+        'tile_id': tile_id,
+        'product_disc_time': product_disc_time,
+        'original_id': product_id
+    }
+
+
+def get_provider(item: Item) -> Optional[StacProvider]:
+    """
+    Determine the STAC provider for a given item.
+    
+    Args:
+        item: STAC Item to analyze
+        
+    Returns:
+        StacProvider instance or None if provider cannot be determined
+    """
+    if not isinstance(item, Item):
+        raise TypeError(f"Expected pystac.Item, got {type(item)}")
+    
+    if not item.self_href:
+        logger.warning(f"Item {item.id} has no self_href")
+        return None
+    for link in item.links:
+        if link.target.startswith('https://earth-search.aws.element84.com/'):
+            return ELEMENT84
+        if link.target.startswith('https://stac.dataspace.copernicus.eu'):
+            return CDSE
+        if link.target.startswith('https://planetarycomputer.microsoft.com/'):
+            return PLANETARYCOMPUTER
+    logger.warning(f"Unknown provider for URL: {item.self_href}")
+    return None
+
+
+def convert_item(item: Item, dst_provider: StacProvider, timeout_hours: int = 1) -> Optional[Item]:
+    """
+    Convert a STAC item from one provider to another.
+    
+    Args:
+        item: Source STAC Item
+        dst_provider: Target provider
+        timeout_hours: Time window to search for matching items
+        
+    Returns:
+        Converted STAC Item or None if not found
+        
+    Raises:
+        ProviderNotFoundError: If source provider cannot be determined
+        S2StacError: If collection type cannot be matched
+    """
+    src_provider = get_provider(item)
+    if src_provider is None:
+        raise ProviderNotFoundError(f"Cannot determine provider for item {item.id}")
+    
+    # Determine target collection
+    if src_provider.l2a == item.collection_id:
+        collection = dst_provider.l2a
+    elif src_provider.l2aold == item.collection_id:
+        collection = dst_provider.l2aold
+    elif src_provider.l1c == item.collection_id:
+        collection = dst_provider.l1c
+    else:
+        # 
+        raise S2StacError(f"Collection {item.collection_id} not matched for provider {src_provider.name}")
+    
+    # Search for matching item
+    try:
+        client = Client.open(dst_provider.url)
+        start_time = item.datetime - timedelta(hours=timeout_hours)
+        end_time = item.datetime + timedelta(hours=timeout_hours)
+        grid_code_key = src_provider.__getattribute__('mgrs_tile')
+        grid_code = item.properties.get(grid_code_key)
+        if src_provider.name == 'planetary-computer':
+            grid_code = f"MGRS-{grid_code}"
+
+        dst_code_key = dst_provider.__getattribute__('mgrs_tile')
+        dst_grid_code = grid_code
+        if dst_provider.name == 'planetary-computer':
+            dst_grid_code = dst_grid_code.replace("MgRS-",'')
+        search = client.search(
+            collections=[collection],
+            datetime=[start_time, end_time],
+            query={
+                dst_code_key: {"eq": dst_grid_code}
+            }
+        )
+        
+        coll = search.item_collection()
+        items = list(coll.items)
+        
+        if not items:
+            logger.warning(f"No {dst_provider.name} product found for item {item.id}")
+            return None
+            
+        if len(items) > 1:
+            # we filter
+            logger.info(f"Multiple {dst_provider.name} products found for item {item.id}, filtering by geom")
+            selitem = filter_items(items, item.geometry)
+            return selitem
+        return items[0]
+        
+    except Exception as e:
+        logger.error(f"Error searching {dst_provider.name} for item {item.id}: {e}")
+        raise S2StacError(f"Failed to search provider {dst_provider.name}: {e}")
+
+
+def change_processing_level(item: Item, timeout_hours: int = 1) -> Optional[Item]:
+    """
+    Convert an item between L1C and L2A processing levels within the same provider.
+    
+    Args:
+        item: Source STAC Item
+        timeout_hours: Time window to search for matching items
+        
+    Returns:
+        Item with different processing level or None if not found
+        
+    Raises:
+        ProviderNotFoundError: If source provider cannot be determined
+        S2StacError: If collection type cannot be matched
+    """
+    src_provider = get_provider(item)
+    if src_provider is None:
+        raise ProviderNotFoundError(f"Cannot determine provider for item {item.id}")
+    
+    # Determine target collection (opposite level)
+    if item.collection_id in [src_provider.l2a,  src_provider.l2aold]:
+        collection = src_provider.l1c
+    elif src_provider.l1c == item.collection_id:
+        collection = src_provider.l2a
+    else:
+        raise S2StacError(f"Collection {item.collection_id} not matched for provider {src_provider.name}")
+    
+    try:
+        client = Client.open(src_provider.url)
+        start_time = item.datetime - timedelta(hours=timeout_hours)
+        end_time = item.datetime + timedelta(hours=timeout_hours)
+        
+        search = client.search(
+            collections=[collection],
+            datetime=[start_time, end_time],
+            query={
+                "grid:code": {"eq": item.properties.get('grid:code')}
+            }
+        )
+        
+        coll = search.item_collection()
+        items = list(coll.items)
+        
+        if not items:
+            logger.warning(f"No {src_provider.name} product found for item {item.id}")
+            return None
+            
+        if len(items) > 1:
+            logger.warning(f"Multiple {src_provider.name} products found for item {item.id}, using first")
+            itemids = [item.id for item in items]
+            logger.info(itemids)
+        
+        return items[0]
+        
+    except Exception as e:
+        logger.error(f"Error changing level for item {item.id}: {e}")
+        raise S2StacError(f"Failed to change processing level: {e}")
+
+
+def get_item_by_id(product_id: str, timeout_hours: int = 1) -> Optional[Item]:
+    """
+    Retrieve a STAC item by its product ID.
+    
+    Args:
+        product_id: Sentinel-2 product identifier
+        timeout_hours: Search timeout (unused for ID-based search)
+        
+    Returns:
+        STAC Item or None if not found
+        
+    Raises:
+        S2StacError: If provider cannot be determined from ID
+    """
+    if not isinstance(product_id, str):
+        raise TypeError(f"Product ID must be a string, got {type(product_id)}")
+    
+    clean_id = product_id.replace('.SAFE', '')
+    
+    # Determine provider based on ID format
+
+    if 'MSIL2A' in clean_id or 'MSIL1C' in clean_id:
+        if len(clean_id.split('_')) == 6:
+            src_provider = PLANETARYCOMPUTER
+        else:
+            src_provider = CDSE
+    elif clean_id.endswith('L2A') or clean_id.endswith("L1C"):
+        src_provider = ELEMENT84
+    else:
+        raise S2StacError(f"Cannot determine provider from ID: {product_id}")
+    
+    try:
+        client = Client.open(src_provider.url)
+        search = client.search(ids=[clean_id])
+        coll = search.item_collection()
+        items = list(coll.items)
+        
+        if not items:
+            logger.warning(f"No {src_provider.name} product found for ID: {product_id}")
+            return None
+            
+        return items[0]
+        
+    except Exception as e:
+        logger.error(f"Error retrieving item {product_id}: {e}")
+        raise S2StacError(f"Failed to retrieve item {product_id}: {e}")
+
+
+
+
+def stac_to_qvf(item, stage="adb"):
+    # TODO: some zone codes are 2 digits
+    # we'll try to deal with either element84 or planetary computer style
+    # 
+    satellite = item.properties['platform']
+    try:
+        grid_code = item.properties['grid:code']
+        tile = S2Scene(grid_code)
+    except KeyError:
+        grid_code = item.properties['s2:mgrs_tile']
+        tile = S2Scene(f"t{grid_code.lower()}")
+
+    when = item.datetime.strftime("%Y%m%d")
+
+    match satellite.lower():
+        case "sentinel-2a":
+            qsensor = "cemsre"
+        case "sentinel-2b":
+            qsensor = "cfmsre"
+        case "sentinel-2c":
+            qsensor = "cgmsre"
+        case _:
+            raise ValueError(f"satellite {satellite} not recognized")
+    # s2scene will be t54kjf
+    # so we want the 3rd element
+    zonecode = tile.qvf_style()[2]
+    qvf_name = f"{qsensor}_{tile.qvf_style()}_{when}_{stage}m{zonecode}.tif"
+    return qvf_name
+
+
+def qvf_to_stac(
+    qvfname: str, 
+    dst_provider: StacProvider = ELEMENT84, 
+    level: str = "l2a",
+    geom: Optional[str] = None
+) -> ItemCollection:
+    """
+    Given a qvf name, find the matching stac item according to the stac provider
+    eg cfmsre_t56jlq_20170808_adbm6.tif
+
+    Args:
+        qvfname: QVF filename to parse
+        dst_provider: STAC provider to search
+        level: Processing level (e.g., 'l2a')
+        geom: Optional geometry as JSON string to filter when there are multiple matches
+
+    Returns:
+        ItemCollection with matching STAC items
+
+    Raises:
+        ValueError: If satellite identifier is not recognized
+    """
+    what, where, when, _ = qvfname.split('_')
+    satellite = what[1]
+    match satellite.lower():
+        case "e":
+            platform = "sentinel-2a"
+        case "f":
+            platform = "sentinel-2b"
+        case "g":
+            platform = "sentinel-2c"
+        case _:
+            raise ValueError(f"satellite {satellite} not recognized")
+
+    date_format = '%Y%m%d'
+    naive_datetime = datetime.strptime(when, date_format)
+    datestring = naive_datetime.strftime("%Y-%m-%d")
+    
+    grid_code = S2Scene(where).mgrs_style()
+    # pc uses slightly different format
+    if dst_provider.name == 'planetary-computer':
+        grid_code = grid_code.replace('MGRS-','')
+    grid_code_key = dst_provider.__getattribute__("mgrs_tile")
+
+    client = Client.open(dst_provider.url)
+    collection = dst_provider.__getattribute__(level)
+    logger.debug(f"{collection=}, {grid_code=}")
+    search = client.search(
+        collections=[collection],
+        datetime=[datestring],
+        query={
+            grid_code_key: {"eq": grid_code}
+        }
+    )
+    coll = search.item_collection()
+    
+    # Filter collections since element84 doesn't use 'in'
+    filtered_items = []
+    for item in coll.items:
+        if item.properties.get('platform', '').lower() == platform:
+            filtered_items.append(item)
+    coll.items = filtered_items
+
+    if len(coll.items) > 1 and geom is not None:
+        matching_item = filter_items(coll.items, geom)
+        coll.items = [matching_item]
+    
+    return coll 
+
+
+def load_polygon_from_geojson(geom_data: str | dict) -> Polygon:
+    """
+    Load polygon from GeoJSON-like data structure
+    
+    Args:
+        geom_data: GeoJSON geometry as string or dictionary
+        
+    Returns:
+        Shapely Polygon object
+        
+    Raises:
+        json.JSONDecodeError: If string cannot be parsed as JSON
+        KeyError: If required 'coordinates' key is missing
+    """
+    if isinstance(geom_data, str):
+        geom_data = json.loads(geom_data)
+    
+    coords = geom_data['coordinates'][0]  # Get exterior ring
+    return Polygon(coords)
+
+
+def calculate_intersection_over_union(poly1: Polygon, poly2: Polygon) -> float:
+    """
+    Calculate IoU (Jaccard index) - higher is better similarity
+    
+    Args:
+        poly1: First polygon
+        poly2: Second polygon
+        
+    Returns:
+        IoU score between 0 and 1, where 1 is perfect overlap
+    """
+    intersection = poly1.intersection(poly2).area
+    union = poly1.union(poly2).area
+    
+    if union == 0:
+        return 0.0
+    return intersection / union
+
+
+    
+def get_largest_polygon_shapely(geojson):
+    """
+    Extract the largest polygon using Shapely.
+    
+    Args:
+        geojson: A GeoJSON dict (Polygon or MultiPolygon)
+        
+    Returns:
+        A GeoJSON Polygon dict with the largest polygon
+    """
+    geom = shape(geojson)
+    
+    # If it's already a Polygon, return as-is
+    if geom.geom_type == 'Polygon':
+        return geojson
+    
+    # If it's a MultiPolygon, get the largest by area
+    if geom.geom_type == 'MultiPolygon':
+        largest = max(geom.geoms, key=lambda p: p.area)
+        return mapping(largest)
+    
+    raise ValueError(f"Unsupported geometry type: {geom.geom_type}")
+
+
+
+def filter_items(items: List[Item], refgeom: str) -> Item:
+    """
+    Filter items by geometry similarity, returning the one with highest IoU
+    
+    Args:
+        items: List of STAC items to filter (must contain exactly 2 items)
+        refgeom: Reference geometry as JSON string
+        
+    Returns:
+        STAC item with highest IoU score against reference geometry
+        
+    Raises:
+        ValueError: If number of items is not exactly 2
+        json.JSONDecodeError: If refgeom cannot be parsed as JSON
+    """
+    if len(items) != 2:
+        raise ValueError(f"Expected exactly 2 items for filtering, got {len(items)}")
+    
+    # make  sure we are using simpl polygons not multi polygons
+    p1 = get_largest_polygon_shapely(items[0].geometry)
+    p2 = get_largest_polygon_shapely(items[1].geometry)
+    
+    poly1 = load_polygon_from_geojson(p1)
+    poly2 = load_polygon_from_geojson(p2)
+    refpoly = load_polygon_from_geojson(refgeom)
+
+    iou1 = calculate_intersection_over_union(poly1, refpoly)
+    iou2 = calculate_intersection_over_union(poly2, refpoly)
+    
+    if iou1 > iou2:
+        return items[0]
+    else:
+        return items[1]
+
+
+def extract_stac_item_from_tiff(tif_file: str) -> Item:
+    """
+    Extract STAC item metadata from a TIFF file.
+    
+    Args:
+        tif_file (str): Path to the TIFF file
+        
+    Returns:
+        pystac.Item: The STAC item object
+        
+    Raises:
+        ValueError: If no SLATS metadata found or metadata cannot be processed
+        ET.ParseError: If GDAL metadata XML cannot be parsed
+    """
+    info = tifftools.read_tiff(str(tif_file))
+    
+    # should be in ifd 0
+    ifd = 0
+    ifd_info = info['ifds'][ifd]
+    tags = ifd_info.get('tags', {})
+    
+    gdal_metadata = None
+    slats_metadata = None
+    
+    for tag_name, tag_data in tags.items():
+        if isinstance(tag_data, dict) and 'data' in tag_data:
+            tag_value = tag_data['data']
+            
+            # Convert tag data to string if it's bytes or a list
+            if isinstance(tag_value, list):
+                try:
+                    tag_value = ''.join([str(x) for x in tag_value])
+                except TypeError:
+                    tag_value = str(tag_value)
+            elif isinstance(tag_value, bytes):
+                tag_value = tag_value.decode('utf-8', errors='ignore')
+            
+            # Check if this is GDAL metadata XML
+            if isinstance(tag_value, str) and tag_value.strip().startswith('<GDALMetadata>'):
+                gdal_metadata = tag_value
+                break
+            # Check if this looks like direct SLATS metadata
+            elif ('SLATS_Metadata2_zipped' in str(tag_name) or 
+                    (isinstance(tag_value, str) and 'SLATS' in tag_value)):
+                slats_metadata = tag_value
+                break
+
+    # Parse GDAL metadata XML to find SLATS_Metadata2_zipped
+    if gdal_metadata and not slats_metadata:
+        try:
+            root = ET.fromstring(gdal_metadata)
+            for item in root.findall('Item'):
+                if item.get('name') == 'SLATS_Metadata2_zipped':
+                    slats_metadata = item.text
+                    break
+        except ET.ParseError as e:
+            raise ET.ParseError(f"Error parsing GDAL metadata XML: {e}")
+    
+    if not slats_metadata:
+        raise ValueError("No SLATS metadata found in TIFF file")
+    
+    # Extract and process metadata
+    mdata = slats_metadata
+    if mdata.startswith(r"b'"):
+        mdata = mdata[2:-1]
+        
+    try:
+        # Decompress and parse
+        decompressed = zlib.decompress(base64.b64decode(mdata))
+        hobj = json.loads(decompressed)
+        json_item = json.loads(hobj['thismeta']['STAC_ITEM'])
+        return Item.from_dict(json_item)
+    except (zlib.error, base64.binascii.Error, json.JSONDecodeError, KeyError) as e:
+        raise ValueError(f"Error processing SLATS metadata: {e}")
+
+
+# concatenate items to create an item collection
+# these may in fact be feature collections
+
+def read_items(url: str)-> List[Item]:
+    """
+    Reads and returns a list of STAC  items from a given URL or file path.
+
+    The input URL or file is expected to represent either a single STAC Item or an ItemCollection.
+    If the input is a single Item, it is wrapped in a list. If it is an ItemCollection, all items
+    within the collection are returned as a list.
+
+    Args:
+        url (str): The URL or file path pointing to a STAC Item or ItemCollection.
+
+    Returns:
+        List[Item]: A list of STAC Items.
+
+    Raises:
+        STACTypeError: If the input file is not a valid STAC Item or ItemCollection.
+    """
+
+    try:
+        items = [Item.from_file(url)]
+    except STACTypeError:
+        jcol = ItemCollection.from_file(url)
+        items = jcol.items 
+    return items

rss_da_stac-0.0.1.dist-info/METADATA

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: rss_da_stac
+Version: 0.0.1
+Summary: Utilities for JRSRP users to interact with common STAC providers
+Author-email: rdenham <robert.denham@detsi.qld.gov.au>
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: planetary-computer>=1.0.0
+Requires-Dist: pystac-client<0.10.0
+Requires-Dist: pystac>=1.13.0
+Requires-Dist: pytz>=2025.2
+Requires-Dist: rasterio>=1.4.3
+Requires-Dist: shapely>=2.1.1
+Requires-Dist: tifftools>=1.6.1
+Requires-Dist: typer>=0.16.0
+Description-Content-Type: text/markdown
+
+# `rss_da_stac` - Python utilities for interacting with common STAC providers
+
+Remote Sensing Scientists associated with the [JRSRP](https://www.jrsrp.org.au/)
+have several established work practices that have been developed over many years,
+and predate STAC and cloud-native Earth Observation (EO) data. 
+
+This package is designed To help integrate
+their current work approaches with modern data providers via STAC. Of particular
+interest is the interoperability of the [`qvf`](https://jrsrp.gitlab.io/sys/meta_info/)
+name convention and how that relates to STAC. Several utilities are designed
+to work with `qvf` style names, such as 
+
+* `qvf2item`: Convert one or more QVF files to a STAC ItemCollection
+* `item2qvf`: Given a stac item or itemcollection, provide the equivalent qvf compliant name for each item. 
+
+
+see [notes](docs/index.md) for details on the included scripts and the API.
+
+
+

rss_da_stac-0.0.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+rss_da_stac/__init__.py,sha256=CO4zZ9hwoQr23X0Ln4Kl6iv7NnkRekc7Pp8eZ6vwPfQ,1051
+rss_da_stac/_version.py,sha256=qf6R-J7-UyuABBo8c0HgaquJ8bejVbf07HodXgwAwgQ,704
+rss_da_stac/cli.py,sha256=qOcZ4GW3-_DSoqqAXHXHj80ViACLMytj0c1jL_IT5pY,7594
+rss_da_stac/uri2l2a.py,sha256=h-baK_XUcpyRMtYEo4v5wdisgv48t8PEaETjpzhrf6k,6321
+rss_da_stac/utils.py,sha256=fAq3WT7uzAp0pVUpSq5rC_1JOQQ2KWYlVmSo55dj6LY,22863
+rss_da_stac-0.0.1.dist-info/METADATA,sha256=K59mE8Vs0taMlbM5VJ6-spyl-ImZvdBKhYgmbICaDXg,1425
+rss_da_stac-0.0.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+rss_da_stac-0.0.1.dist-info/entry_points.txt,sha256=J6QnpfgGs8fP0M5Y9xFX4HNUgc0AsZRyrhw_cVgN_48,83
+rss_da_stac-0.0.1.dist-info/licenses/LICENSE,sha256=VRrbB2lTGdV85ryNqQM4kPuADiUfyfZk0C6TvccpCCc,908
+rss_da_stac-0.0.1.dist-info/RECORD,,

rss_da_stac-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

rss_da_stac-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+rss-stac = rss_da_stac.cli:app
+uri2l2a = rss_da_stac.uri2l2a:app

rss_da_stac-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,18 @@
+MIT No Attribution
+
+Copyright 2025 Robert Denham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.