Search Factory

Overview

The sat_download.factories.search module provides factory functions for creating SatelliteImage objects from raw API response data.

---

API Reference

Main Factory

get_satellite_image

get_satellite_image(
    collection: COLLECTIONS, data: dict
) -> SatelliteImage

Factory function to create a SatelliteImage object based on collection type and metadata.

Parameters:

Name	Type	Description	Default
collection	COLLECTIONS	The satellite collection enum indicating the source platform	required
data	dict	Dictionary containing metadata about the satellite image	required

Returns:

Type	Description
SatelliteImage	A standardized satellite image object with extracted metadata

Notes

This function delegates to specialized parsers for each collection type. The 'Name' field in the data dictionary is required for all collection types.

Source code in sat_download\factories\search.py

def get_satellite_image(collection: COLLECTIONS, data: dict) -> SatelliteImage:
    """
    Factory function to create a SatelliteImage object based on collection type and metadata.

    Parameters
    ----------
    collection : COLLECTIONS
        The satellite collection enum indicating the source platform
    data : dict
        Dictionary containing metadata about the satellite image

    Returns
    -------
    SatelliteImage
        A standardized satellite image object with extracted metadata

    Notes
    -----
    This function delegates to specialized parsers for each collection type.
    The 'Name' field in the data dictionary is required for all collection types.
    """
    if collection == COLLECTIONS.SENTINEL_2:
        result = get_sentinel2(collection.value.lower().capitalize(), data['Name'])
    elif collection == COLLECTIONS.SENTINEL_3:
        result = get_sentinel3(collection.value.lower().capitalize(), data['Name'])
    elif collection == COLLECTIONS.LANDSAT_8:
        result = get_landsat_8('Landsat-8', data['Name'])

    return result

---

Specialized Parsers

get_sentinel2

get_sentinel2(satellite: str, name: str) -> SatelliteImage

Parse Sentinel-2 image metadata from filename.

Parameters:

Name	Type	Description	Default
satellite	str	The satellite platform name ('Sentinel-2')	required
name	str	The original filename containing metadata components	required

Returns:

Type	Description
SatelliteImage	A standardized satellite image object with extracted metadata

Notes

Extracts date, satellite brother (A/B), UUID, and tile information from standard Sentinel-2 filename format.

Source code in sat_download\factories\search.py

def get_sentinel2(satellite: str, name: str) -> SatelliteImage:
    """
    Parse Sentinel-2 image metadata from filename.

    Parameters
    ----------
    satellite : str
        The satellite platform name ('Sentinel-2')
    name : str
        The original filename containing metadata components

    Returns
    -------
    SatelliteImage
        A standardized satellite image object with extracted metadata

    Notes
    -----
    Extracts date, satellite brother (A/B), UUID, and tile information
    from standard Sentinel-2 filename format.
    """
    components = name.split('_')
    satellite_position = 0
    date_position = 2
    tile_position = -2

    date: str = components[date_position].split('T')[0]
    brother: str = components[satellite_position][-1]
    uuid: str = f"{date}_{components[satellite_position]}"
    tile: str = components[tile_position][1:]

    result: SatelliteImage = SatelliteImage(uuid=uuid, date=date, sensor=satellite, 
                                            brother=brother, identifier=f"{satellite}{brother}", 
                                            tile=tile, filename=f"{name.split('.')[0]}.zip")
    return result

get_sentinel3

get_sentinel3(satellite: str, name: str) -> SatelliteImage

Parse Sentinel-3 image metadata from filename.

Parameters:

Name	Type	Description	Default
satellite	str	The satellite platform name ('Sentinel-3')	required
name	str	The original filename containing metadata components	required

Returns:

Type	Description
SatelliteImage	A standardized satellite image object with extracted metadata

Notes

Extracts date, satellite brother (A/B), UUID, and tile information from standard Sentinel-3 filename format.

Source code in sat_download\factories\search.py

def get_sentinel3(satellite: str, name: str) -> SatelliteImage:
    """
    Parse Sentinel-3 image metadata from filename.

    Parameters
    ----------
    satellite : str
        The satellite platform name ('Sentinel-3')
    name : str
        The original filename containing metadata components

    Returns
    -------
    SatelliteImage
        A standardized satellite image object with extracted metadata

    Notes
    -----
    Extracts date, satellite brother (A/B), UUID, and tile information
    from standard Sentinel-3 filename format.
    """
    components = name.split('_')
    satellite_position = 0
    date_position = 7
    tile_position = 11

    date: str = components[date_position].split('T')[0]
    brother: str = components[satellite_position][-1]
    uuid: str = f"{date}_{components[satellite_position]}"
    tile: str = components[tile_position]

    result: SatelliteImage = SatelliteImage(uuid=uuid, date=date, sensor=satellite, 
                                            brother=brother, identifier=f"{satellite}{brother}", 
                                            tile=tile, filename=f"{name.split('.')[0]}.zip")
    return result

get_landsat_8

get_landsat_8(satellite: str, name: str) -> SatelliteImage

Parse Landsat-8 image metadata from filename.

Parameters:

Name	Type	Description	Default
satellite	str	The satellite platform name ('Landsat-8')	required
name	str	The original filename containing metadata components	required

Returns:

Type	Description
SatelliteImage	A standardized satellite image object with extracted metadata

Notes

Extracts date, satellite collection number, UUID, and tile information from standard Landsat-8 filename format.

Source code in sat_download\factories\search.py

def get_landsat_8(satellite: str, name: str) -> SatelliteImage:
    """
    Parse Landsat-8 image metadata from filename.

    Parameters
    ----------
    satellite : str
        The satellite platform name ('Landsat-8')
    name : str
        The original filename containing metadata components

    Returns
    -------
    SatelliteImage
        A standardized satellite image object with extracted metadata

    Notes
    -----
    Extracts date, satellite collection number, UUID, and tile information
    from standard Landsat-8 filename format.
    """
    components = name.split('_')
    tile = components[2]
    date = components[3]
    brother = components[0][-1]
    uuid = f'L{brother}_{date}'
    result: SatelliteImage = SatelliteImage(uuid=uuid, date=date, sensor=satellite, 
                                            brother=brother, identifier=f'{satellite[:-1] + brother}', 
                                            filename=f"{name.split('.')[0]}.tar", tile=tile)

    return result

---

Factory Flow

flowchart TD
    A[get_satellite_image] --> B{Collection Type?}
    B -->|SENTINEL_2| C[get_sentinel2]
    B -->|SENTINEL_3| D[get_sentinel3]
    B -->|LANDSAT_8| E[get_landsat_8]
    C --> F[SatelliteImage]
    D --> F
    E --> F

---

Usage Examples

Basic Usage

from sat_download.factories.search import get_satellite_image
from sat_download.enums import COLLECTIONS

# Sentinel-2 data from API response
api_data = {
    'Name': 'S2A_MSIL2A_20240115T105421_N0510_R051_T30TWM_20240115T142543.SAFE'
}

# Create SatelliteImage object
image = get_satellite_image(COLLECTIONS.SENTINEL_2, api_data)

print(f"Date: {image.date}")       # 20240115
print(f"Tile: {image.tile}")       # 30TWM
print(f"Sensor: {image.sensor}")   # Sentinel-2
print(f"File: {image.filename}")   # S2A_MSIL2A_20240115T105421_N0510_R051_T30TWM_20240115T142543.zip

Landsat 8 Example

from sat_download.factories.search import get_satellite_image
from sat_download.enums import COLLECTIONS

# Landsat 8 data from API response
api_data = {
    'Name': 'LC08_L1TP_203033_20240115_20240125_02_T1'
}

# Create SatelliteImage object
image = get_satellite_image(COLLECTIONS.LANDSAT_8, api_data)

print(f"Date: {image.date}")       # 20240115
print(f"Tile: {image.tile}")       # 20303320240115
print(f"Sensor: {image.sensor}")   # Landsat-8
print(f"File: {image.filename}")   # LC08_L1TP_203033_20240115_20240125_02_T1.tar

---

Filename Formats

Sentinel-2 Format

S2A_MSIL2A_20240115T105421_N0510_R051_T30TWM_20240115T142543.SAFE
│   │      │               │     │    │      │
│   │      │               │     │    │      └─ Processing timestamp
│   │      │               │     │    └─ Tile ID (T30TWM)
│   │      │               │     └─ Relative orbit
│   │      │               └─ Processing baseline
│   │      └─ Acquisition date/time
│   └─ Product type (MSIL2A)
└─ Satellite (S2A = Sentinel-2A)

Landsat 8 Format

LC08_L1TP_203033_20240115_20240125_02_T1
│    │    │      │        │        │  │
│    │    │      │        │        │  └─ Collection tier (T1)
│    │    │      │        │        └─ Collection number
│    │    │      │        └─ Processing date
│    │    │      └─ Acquisition date
│    │    └─ Path/Row (203/033)
│    └─ Product type (L1TP)
└─ Satellite (LC08 = Landsat 8)

---

Adding New Satellite Support

To add support for a new satellite, create a parser function:

def get_new_satellite(satellite: str, name: str) -> SatelliteImage:
    """
    Parse metadata from new satellite filename format.

    Parameters
    ----------
    satellite : str
        The satellite platform name
    name : str
        The original filename

    Returns
    -------
    SatelliteImage
        Standardized satellite image object
    """
    # Parse filename components
    components = name.split('_')

    # Extract metadata
    date = components[DATE_POSITION]
    brother = components[SATELLITE_POSITION][-1]
    uuid = f"{date}_{components[SATELLITE_POSITION]}"
    tile = components[TILE_POSITION]

    return SatelliteImage(
        uuid=uuid,
        date=date,
        sensor=satellite,
        brother=brother,
        identifier=f"{satellite}{brother}",
        tile=tile,
        filename=f"{name}.zip"
    )

Then update get_satellite_image():

def get_satellite_image(collection: COLLECTIONS, data: dict) -> SatelliteImage:
    if collection == COLLECTIONS.NEW_SATELLITE:
        result = get_new_satellite(collection.value, data['Name'])
    # ... existing cases
    return result

---

Design Pattern

This module implements the Factory Method Pattern:

• get_satellite_image() is the factory method
• Specialized parsers handle collection-specific logic
• All return the same SatelliteImage type

See: Design Patterns

---

References

• SatelliteImage - Output data type
• COLLECTIONS - Collection identifiers
• Sentinel-2 Naming Convention
• Landsat Naming Convention