smosaic API

Mosaic Creation

smosaic.smosaic_mosaic.mosaic(name, data_dir, stac_url, collection, output_dir, start_year, start_month, start_day, mosaic_method, grid_crop=False, bands=None, reference_date=None, duration_days=None, end_year=None, end_month=None, end_day=None, duration_months=None, geom=None, grid=None, tile_id=None, bbox=None, profile=None, projection_output=4326)

Create satellite image mosaics using Brazil Data Cube collections.

This function generates temporal composites from Brazil Data Cube STAC collections by applying specified mosaic composition function over defined time periods and spatial extents. It supports BDC’s grid systems, diferent projections, and composition function.

Parameters:

• name (str) – Descriptive identifier for the output mosaic (used in file naming).

• data_dir (str) – Directory for storing intermediate data and processing artifacts.

• stac_url (str) – Brazil Data Cube STAC API endpoint URL (e.g., “https://data.inpe.br/bdc/stac/v1”).

• collection (str) – BDC collection identifier (e.g., “S2_L2A-1”).

• output_dir (str) – Destination directory for final mosaic products.

• start_year (int) – Initial year for temporal filtering (YYYY format).

• start_month (int) – Initial month for temporal filtering (1-12).

• start_day (int) – Initial day for temporal filtering (1-31).

• mosaic_method (str) – Mosaic composition function. Supported methods include: - “lcf”: Least Cloud-cover First - order by the least cloud-cover. - “chrono”: Chronological - order chronologicaly. - “ctd”: Closest to Date - order by the closest image to reference date.

• grid_crop (bool, optional) – Enable cropping to BDC grid tile boundaries. Defaults to False.

• bands (list, optional) – Spectral bands to include (e.g., [“B02”,”B03”,”B04”,”B8A”]).

• reference_date (str, optional) – Reference date for the Closest to Date composition function. (format: ‘YYYY-MM-DD’).

• duration_days (int, optional) – Temporal window length in days from start date (day/month/year).

• end_year (int, optional) – Explicit end year for temporal range (YYYY format). Defaults to None.

• end_month (int, optional) – Explicit end month for temporal range (1-12). Defaults to None.

• end_day (int, optional) – Explicit end day for temporal range (1-31). Defaults to None.

• duration_months (int, optional) – Temporal window length in months from start date (day/month/year).

• geom (str/dict, optional) – GeoJSON geometry defining Area of Interest (AOI). Defaults to None.

• grid (str, optional) – BDC grid system identifier. Supported grids include: - “BDC_SM_V2”: Brazil Data Cube Small Grid. Defaults to None.

• tile_id (str, optional) – BDC grid tile identifier (6-digit code, e.g., “020019”). Requires grid parameter. Defaults to None.

• bbox (list/tuple, optional) – Bounding box coordinates [min_lon, min_lat, max_lon, max_lat].

• profile (dict, optional) – Profile band and spectral indices: selector. Overrides bands parameters (e.g., “urban_analysis” or “crop_condition”).

• projection_output (int/str, optional) – Output coordinate reference system. Options: - EPSG codes: 4326 (WGS84), 5880 (SIRGAS 2000 Brazil Polyconic) - BDC codes: “BDC” (Brazil Data Cube Standard Grid projection) Defaults to 4326.

Example

>>> import os
>>> from smosaic import mosaic
>>>
>>> stac_url = "https://data.inpe.br/bdc/stac/v1"
>>>
>>> result = mosaic(
...     name="MT",
...     data_dir=os.path.abspath(""),
...     stac_url=stac_url,
...     collection="S2_L2A-1",
...     grid="BDC_SM_V2",
...     tile_id="020019",
...     projection_output="BDC",
...     output_dir=os.path.join("output"),
...     mosaic_method="lcf",
...     start_year=2026,
...     start_month=1,
...     start_day=1,
...     duration_days=16,
...     bands=["B02","B03","B04"]
... )

Returns:

Path to the generated mosaic file.

Return type:

str

Data Collection

smosaic.smosaic_collection_get_data.collection_get_data(stac, datacube, data_dir)

Fetch and download data from a STAC collection based on specified parameters.

Parameters:

• stac (str) – Brazil Data Cube STAC API endpoint URL (e.g., “https://data.inpe.br/bdc/stac/v1”).

• datacube (dict) – Dictionary containing collection query parameters with the following keys: collection (str): Identifier of the STAC collection to query. start_date (str): Start date for temporal filtering in ‘YYYY-MM-DD’ format. end_date (str): End date for temporal filtering in ‘YYYY-MM-DD’ format. bbox (list/tuple): Bounding box coordinates [minx, miny, maxx, maxy] for spatial filtering. bands (list, optional): List of band identifiers to include in the download.

• data_dir (str) – Directory path where the downloaded data will be stored.

smosaic.smosaic_download_stream.download_stream(file_path: str, response, chunk_size=65536, progress=True, offset=0, total_size=None)

Download request stream data to disk.

Parameters:

• save (file_path - Absolute file path to)

• object (response - HTTP Response)

Raster Processing

smosaic.smosaic_filter_scenes.filter_scenes(collection, data_dir, geom)

Filter and select specific scenes from a collection based on spatial criteria.

Parameters:

• collection (str) – BDC collection identifier (e.g., “S2_L2A-1”).

• data_dir (str) – Directory path where scene data is stored.

• clip_geometry (shapely.geometry) – Spatial boundary for clipping.

smosaic.smosaic_count_pixels.count_pixels(raster_path, target_values, geom)

Counts pixels matching target_values within the intersection of the raster and a geometry.

Parameters:

• raster_path (str) – Path to the raster file.

• target_values (list) – List of pixel values to count.

• geom (shapely.geometry) – Geometry object (e.g., Polygon) in EPSG:4326 (Lat/Lon).

Returns:

‘total’: Total count of valid pixels inside the geometry (including 0s). ‘count’: Count of pixels matching target_values inside the geometry.

Return type:

dict

smosaic.smosaic_reproject_tif.reproject_tifs(sorted_data, cloud_sorted_data, data_dir, projection_output)

Reproject a list of TIFF files and their corresponding cloud mask files to a target coordinate system.

Parameters:

• sorted_data (list) – List of raster files sorted by the mosaic composition function. Each element contains file metadata including date, scene, band, and sorting function.

• cloud_sorted_data (list) – List of cloud cover data files sorted by the mosaic composition function. Used for cloud scene in mosaic generation.

• data_dir (str) – Directory path where reprojected files will be saved.

• projection_output (int/str) – Output coordinate reference system. Options: - EPSG codes: 4326 (WGS84), 5880 (SIRGAS 2000 Brazil Polyconic) - BDC codes: “BDC” (Brazil Data Cube Standard Grid projection)

smosaic.smosaic_merge_scene.merge_scene(sorted_data, cloud_sorted_data, scenes, collection_name, band, data_dir, start_date=None, end_date=None)

Merge and organize raster scenes based on mosaic composition function and cloud cover data.

Parameters:

• sorted_data (list) – List of raster files sorted by the mosaic composition function. Each element contains file metadata including date, scene, band, and sorting function.

• cloud_sorted_data (list) – List of cloud cover data files sorted by the mosaic composition function.. Used for cloud-aware scene selection in mosaic generation.

• scenes (list) – List of scene identifiers to be processed.

• collection_name (str) – Name of the collection or dataset being processed.

• band (str) – Spectral band identifier being processed.

• data_dir (str) – Directory path where scene data is stored.

• start_date (str, optional) – Start date for temporal filtering in ‘YYYY-MM-DD’ format. Defaults to None.

• end_date (str, optional) – End date for temporal filtering in ‘YYYY-MM-DD’ format. Defaults to None.

smosaic.smosaic_merge_scene.merge_scene_provenance_cloud(sorted_data, cloud_sorted_data, scenes, collection_name, band, data_dir, start_date=None, end_date=None)

Merge and organize raster scenes, including cloud band and provenance data, based on mosaic composition function.

Parameters:

• sorted_data (list) – List of raster files sorted by the mosaic composition function. Each element contains file metadata including date, scene, band, and sorting function.

• cloud_sorted_data (list) – List of cloud cover data files sorted by the mosaic composition function. Used for cloud scene in mosaic generation.

• scenes (list) – List of scene identifiers to be processed.

• collection_name (str) – Name of the collection or dataset being processed.

• band (str) – Spectral band identifier being processed.

• data_dir (str) – Directory path where scene data is stored.

• start_date (str, optional) – Start date for temporal filtering in ‘YYYY-MM-DD’ format. Defaults to None.

• end_date (str, optional) – End date for temporal filtering in ‘YYYY-MM-DD’ format. Defaults to None.

smosaic.smosaic_merge_tifs.merge_tifs(tif_files, output_path, band, path_row=None, extent=None)

Merge multiple TIFF files into a single TIFF file using GDAL merge.

Parameters:

• tif_files (list) – List of input TIFF file paths to merge.

• output_path (str) – Path for the output merged TIFF file.

• band (str) – Spectral band identifier for the merged output.

• path_row (str, optional) – Path/row identifier for satellite data organization. Defaults to None.

• extent (tuple/list, optional) – Spatial extent for the merged output as [minx, miny, maxx, maxy]. If None, uses the combined extent of all input files. Defaults to None.

smosaic.smosaic_clip_raster.clip_raster(input_raster_path, output_folder, clip_geometry, projection_output, output_filename=None, grid=None, tile_id=None)

Extract a spatial subset from a raster file using a geometry or grid tile.

Parameters:

• input_raster_path (str) – Full path to the input raster file (GeoTIFF format).

• output_folder (str) – Directory path where the clipped raster will be saved.

• clip_geometry (shapely.geometry) – Spatial boundary for clipping.

• projection_output (int/str, optional) – Output coordinate reference system. Options: - EPSG codes: 4326 (WGS84), 5880 (SIRGAS 2000 Brazil Polyconic) - BDC codes: “BDC” (Brazil Data Cube Standard Grid projection) Defaults to 4326.

• output_filename (str, optional) – Custom name for output file (without directory path). If None, generated from input filename and clip parameters. Defaults to None.

• grid (str, optional) – BDC grid system identifier. Supported grids include: - “BDC_SM_V2”: Brazil Data Cube Small Grid. Defaults to None.

• tile_id (str, optional) – BDC grid tile identifier (6-digit code, e.g., “020019”). Requires grid parameter. Defaults to None.

Returns:

Absolute path to the generated clipped raster file.

Return type:

str

smosaic.smosaic_fix_baseline_number.fix_baseline_number(input_folder: str, input_filename: str, baseline_number: str) → str

Adjust image value based on the baseline number in a file’s naming .

Parameters:

• input_folder (str) – Directory path containing the input file.

• input_filename (str) – Name of the input file to be processed.

• baseline_number (str) – Baseline number to assign or correct in the file.

Returns:

Path or identifier of the processed file with the updated baseline number.

Return type:

str

smosaic.smosaic_generate_cog.generate_cog(input_folder: str, input_filename: str, compress: str = 'LZW') → str

Generate a Cloud Optimized GeoTIFF (COG) from a raster file.

Parameters:

• input_folder (str) – Directory path containing the input raster file.

• input_filename (str) – Name of the input raster file to convert to COG format.

• compress (str, optional) – Compression method to use for the output COG. Common options: ‘LZW’, ‘DEFLATE’, ‘JPEG’, ‘PACKBITS’. Defaults to ‘LZW’.

Returns:

Path to the generated Cloud Optimized GeoTIFF file.

Return type:

str

smosaic.smosaic_spectral_indices.calculate_spectral_indices(input_folder: str, spectral_indices) → str

Calculate spectral indices from raster data, used with profile “urban_analysis” or “crop_condition”.

Parameters:

• input_folder (str) – Directory path containing the input raster files for index calculation.

• spectral_indices (list) – List of spectral indices to calculate. Each element is a string identifier of a spectral index (e.g., “NDVI”, “EVI”, “EVI2”, “SAVI”).

smosaic.smosaic_grid_crop.clip_from_grid(input_folder, grid, tile_id, projection_output)

Clip raster data from a specified grid tile within a given grid system.

Parameters:

• input_folder (str) – Directory path containing the input raster files to clip.

• grid (str, optional) – BDC grid system identifier. Supported grids include: - “BDC_SM_V2”: Brazil Data Cube Small Grid.

• tile_id (str, optional) – BDC grid tile identifier (6-digit code, e.g., “020019”). Requires grid parameter. Defaults to None.

• projection_output (int/str, optional) – Output coordinate reference system. Options: - EPSG codes: 4326 (WGS84), 5880 (SIRGAS 2000 Brazil Polyconic) - BDC codes: “BDC” (Brazil Data Cube Standard Grid projection) Defaults to 4326.

smosaic.smosaic_grid_crop.get_tiles_intersecting_tif(tif_path, grid, projection_output)

Identify grid tiles that intersect with a given GeoTIFF file’s spatial extent.

Parameters:

• tif_path (str) – Path to the input GeoTIFF file.

• grid (str, optional) – BDC grid system identifier. Supported grids include: - “BDC_SM_V2”: Brazil Data Cube Small Grid.

• projection_output (int/str, optional) – Output coordinate reference system. Options: - EPSG codes: 4326 (WGS84), 5880 (SIRGAS 2000 Brazil Polyconic) - BDC codes: “BDC” (Brazil Data Cube Standard Grid projection) Defaults to 4326.

smosaic.smosaic_utils.add_days_to_date(start_date, days_to_add)

Add a specified number of days to a given date.

Parameters:

• start_date (datetime/str) – The starting date.

• days_to_add (int) – The number of days to add (positive or negative).

Returns:

The new date after adding the specified number of days.

Return type:

datetime

smosaic.smosaic_utils.add_months_to_date(start_date, months_to_add)

Add months to a date and return the last day of the FINAL month. (Fixes the issue where adding N months would overshoot)

Parameters:

• start_date (datetime/str) – Starting date

• months_to_add (int) – Months to add (positive or negative)

Returns:

Last day of the target month

Return type:

datetime

smosaic.smosaic_utils.create_composition_json(output_dir, collection, input_scenes, ignored_scenes, used_scenes)

Create composition.json file with optional custom data

smosaic.smosaic_utils.days_between_dates(date1, date2)

Calculate the number of days between two dates.

Parameters:

• date1 (str) – First date in ‘YYYY-MM-DD’ format

• date2 (str) – Second date in ‘YYYY-MM-DD’ format

Returns:

Number of days between the two dates (positive if date2 is after date1, negative if date2 is before date1)

Return type:

int

smosaic.smosaic_utils.get_all_cloud_configs() → Dict[str, Dict[str, Any]]

Get all cloud configurations.

Returns:

Dictionary of all cloud configurations

smosaic.smosaic_utils.get_coverage_projection() → CRS

Get the coverage projection CRS.

Returns:

pyproj.CRS object for the coverage projection

smosaic.smosaic_utils.load_json_config(file_path: str, use_cache: bool = True) → Dict[str, Any]

Load JSON configuration from a file with optional caching.

Parameters:

• file_path – Path to the JSON file

• use_cache – If True, cache the result for subsequent calls

Returns:

Dictionary containing the JSON data

smosaic.smosaic_utils.open_geojson(file_path)

Load and convert a GeoJSON file to a shapely geometry object.

Parameters:

file_path (str) – Path to the GeoJSON file to be loaded.

Returns:

A shapely geometry object representing the geometry in the GeoJSON file.

Return type:

shapely.geometry.base.BaseGeometry