dronewq.core package

Submodules

dronewq.core.geometry module

class dronewq.core.geometry.Paralelogram2D(points)

Bases: object

Represents a 2D parallelogram defined by four corner points.

The class assumes the points are ordered consecutively around the shape. It automatically determines the line segments and opposite-line pairs.

Parameters:

points (np.ndarray (shape: (4, 2))) – Array of the four corner points of the parallelogram, ordered clockwise or counter-clockwise.

are_on_right_side_of_line(index, points)

Check whether a list of points lies on the right side of the specified line segment.

Parameters:

  • index (int) – Line index.

  • points (np.ndarray (shape: (N, 2))) – Points to test.

Returns:

True if all points lie on the right side of the line, otherwise False.

Return type:

bool

get_center()

Compute the centroid of the parallelogram.

Returns:

np.ndarray (shape – The center point of the parallelogram.

Return type:

(2,))

get_line_center(index)

Compute the midpoint of one of the parallelogram’s edges.

Parameters:

index (int) – Index of the line segment in self.lines.

Returns:

np.ndarray (shape – The midpoint of the selected line.

Return type:

(2,))

get_offset_to_lines(index, point)

Compute a vector pointing from a point toward the center of a specific edge.

Parameters:

  • index (int) – Line index.

  • point (np.ndarray (shape: (2,))) – The reference point.

Returns:

np.ndarray (shape – Direction vector pointing toward the line’s midpoint.

Return type:

(2,))

move_line_from_offset(index, offset)

Translate a line segment by a given offset vector. This moves the two points belonging to the line.

Parameters:

  • index (int) – Line index.

  • offset (np.ndarray (shape: (2,))) – Offset vector applied to the line’s two endpoints.

dronewq.core.geometry.are_points_within_vertices(vertices, points)

Check whether multiple points all lie inside a polygon.

Parameters:

  • vertices (List[Tuple[float, float]]) – Ordered polygon vertices.

  • points (List[Tuple[float, float]] or np.ndarray) – Points to test.

Returns:

True if every point is inside or on the polygon boundary.

Return type:

bool

dronewq.core.geometry.euclidean_distance(p1, p2)

Compute the 2D Euclidean distance between two points.

Parameters:

  • p1 (Tuple[float, float]) – Input points.

  • p2 (Tuple[float, float]) – Input points.

Returns:

Euclidean distance.

Return type:

float

dronewq.core.geometry.get_center(points)

Compute the centroid (mean point) of a list of 2D points.

Parameters:

points (np.ndarray (shape: (N, 2))) – Array of points.

Returns:

np.ndarray (shape – The centroid of the points.

Return type:

(2,))

dronewq.core.geometry.is_on_right_side(x, y, xy0, xy1)

Determine whether a point lies on the right side of a directed line.

The line is interpreted as directed from xy0 to xy1. “Right side” is computed using the standard 2D line equation.

Parameters:

  • x (float) – Coordinates of the point to test.

  • y (float) – Coordinates of the point to test.

  • xy0 (Tuple[float, float]) – Two points defining the directed line segment.

  • xy1 (Tuple[float, float]) – Two points defining the directed line segment.

Returns:

True if the point is on the right side of the line, otherwise False.

Return type:

bool

dronewq.core.geometry.is_point_within_vertices(x, y, vertices)

Check whether a point lies inside or on the boundary of a polygon.

The polygon is defined by a list of vertices in order. The method checks whether the point lies consistently on the same side (all left or all right) of every polygon edge.

Parameters:

  • x (float) – Coordinates of the point to test.

  • y (float) – Coordinates of the point to test.

  • vertices (List[Tuple[float, float]]) – Ordered list of polygon vertices.

Returns:

True if the point is inside or on the polygon boundary.

Return type:

bool

dronewq.core.georeference module

dronewq.core.mosaic module

dronewq.core.mosaic_methods module

dronewq.core.pipeline module

dronewq.core.plot_map module

dronewq.core.plot_map.plot_basemap(ax: Axes, west: float, south: float, east: float, north: float, zoom: str = 'auto', source: str | Bunch = {'attribution': '(C) OpenStreetMap contributors', 'html_attribution': '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors', 'max_zoom': 19, 'name': 'OpenStreetMap.Mapnik', 'url': 'https://tile.openstreetmap.org/{z}/{x}/{y}.png'}, clip: bool = False) → Axes

This function loads a basemap and plot in the axes provides using pseudo-Mercator projection (epsg:3857).

NOTE:

  • west, east, south and north must longitudes and latitudes based on crs=epsg:4326.

  • local basemaps like Sentinel-2 must be georeferenced with crs=epsg:4326.

  • If basemap param is a string (filename) it is loaded and plotted; Otherwise a basemap is searched with contextily based on west, east, south and north params.

Parameters

ax (Axes): axes where to plot west (float): minimum longitude south (float): minimum latitude east (float): maximum longitude north (float): maximum latitude zoom (str): zoom level of the contextily basemap source (str | Bunch, optional): Filename or Basemap provider from contextily to plot. Defaults to cx.providers.OpenStreetMap.Mapnik. clip (bool, optional): If True and source is a filename, the local basemap will be clipped base on west, east, south and north params. Defaults to False.

Returns

Axes: axes with the basemap plotted

dronewq.core.plot_map.plot_georeferenced_data(ax: Axes, filename: str, vmin: float, vmax: float, cmap: str, norm: None = None, zoom: str = 'auto', basemap: Bunch | str = {'attribution': '(C) OpenStreetMap contributors', 'html_attribution': '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors', 'max_zoom': 19, 'name': 'OpenStreetMap.Mapnik', 'url': 'https://tile.openstreetmap.org/{z}/{x}/{y}.png'}) → tuple[Axes, AxesImage]

Loads a single-band GeoTIFF, projects it to pseudo-Mercator (EPSG:3857), and plots it over the given matplotlib Axes.

Args:

ax (Axes): Matplotlib axes to plot on. filename (str): Path to GeoTIFF file. vmin (float): Minimum colormap value. vmax (float): Maximum colormap value. cmap (str): Matplotlib colormap name. norm (optional): Colormap normalization (e.g. LogNorm). Default None. zoom (optional): Zoom level of the basemap. basemap (optional): Contextily basemap provider or path. Default None.

Returns:

Tuple[Axes, AxesImage]: The plot axes and the raster mappable.

dronewq.core.wq_calc module

dronewq.core.wq_calc.chl_gitelson(Rrs)

Compute chlorophyll-a using the Gitelson et al. (2007) two-band algorithm.

Designed primarily for optically complex (Case-2) waters and uses the red and red-edge bands.

Reference: Gitelson et al., 2007. doi:10.1016/j.rse.2007.01.016

Parameters:

Rrs (numpy.ndarray) – Reflectance array of shape (bands, height, width). Expected bands: red, red-edge.

Returns:

Chlorophyll-a concentration (mg m⁻³).

Return type:

numpy.ndarray

dronewq.core.wq_calc.chl_hu(Rrs)

Compute chlorophyll-a using the Hu et al. (2012) Color Index (CI) algorithm.

This three-band reflectance difference algorithm is recommended for very low chlorophyll concentrations (< 0.15 mg m⁻³). See: https://oceancolor.gsfc.nasa.gov/atbd/chlor_a/

Parameters:

Rrs (numpy.ndarray) – Array of remote-sensing reflectances with shape (bands, height, width). Expected bands: blue, green, red.

Returns:

Chlorophyll-a estimate (mg m⁻³).

Return type:

numpy.ndarray

dronewq.core.wq_calc.chl_hu_ocx(Rrs)

Compute chlorophyll-a using the blended NASA CI/OCx algorithm.

This algorithm blends the Hu Color Index (chl_hu) and OCx (chl_ocx) algorithms using a threshold-based transition region: - CI dominates below 0.15 mg m⁻³ - OCx dominates above 0.20 mg m⁻³ - Linear blend in the transition region

Implementation follows the NASA HyperInSPACE reference: https://www.earthdata.nasa.gov/apt/documents/chlor-a/v1.0

Parameters:

Rrs (numpy.ndarray) – Reflectance array of shape (bands, height, width).

Returns:

Chlorophyll-a estimate (mg m⁻³).

Return type:

numpy.ndarray

dronewq.core.wq_calc.chl_ocx(Rrs)

Compute chlorophyll-a using the O’Reilly OCx band-ratio algorithm.

Implements a fourth-order polynomial relationship using the OC2 coefficients for Landsat-8 (O’Reilly et al., 1998). Best suited for chlorophyll levels above ~0.2 mg m⁻³.

Documentation: https://oceancolor.gsfc.nasa.gov/atbd/chlor_a/

Parameters:

Rrs (numpy.ndarray) – Array of reflectances with shape (bands, height, width). Expected bands: blue, green.

Returns:

Chlorophyll-a estimate (mg m⁻³).

Return type:

numpy.ndarray

dronewq.core.wq_calc.save_wq(arr: ndarray, output_path: Path, profile: dict)

Saves a 2D numpy array to band 1 of a raster file using windowed writing.

dronewq.core.wq_calc.save_wq_imgs(rrs_dir: Path | str, wq_algs: list[str] = ['chl_gitelson'], start: int = 0, count: int = 10000, num_workers: int = 4)

Generate and save water-quality (WQ) products from Rrs rasters.

This function loads Rrs raster files from rrs_dir, applies the specified water-quality algorithms (e.g., chlorophyll or TSM retrieval algorithms), and writes the results as new GeoTIFF files in dedicated subdirectories under settings.main_dir.

Parameters:

rrs_dir (str | Path) – Directory containing input Rrs raster files.

wq_algslist[str], optional

List of algorithm names to apply. Supported values: "chl_hu", "chl_ocx", "chl_hu_ocx", "chl_gitelson", "tsm_nechad". Default is ["chl_gitelson"].

startint, optional

Starting index when selecting which Rrs files to process. Default is 0.

countint, optional

Maximum number of images to process. Default is 10000.

num_workersint, optional

Number of worker processes to use if no executor is provided.

dronewq.core.wq_calc.tsm_nechad(Rrs)

Estimate Total Suspended Matter (TSM) using the Nechad et al. (2010) algorithm.

Uses a semi-empirical relationship based on red-band reflectance.

Reference: Nechad et al., 2010. doi:10.1016/j.rse.2009.11.022

Parameters:

Rrs (numpy.ndarray) – Reflectance array of shape (bands, height, width). Expected band: red.

Returns:

TSM concentration (mg m⁻³).

Return type:

numpy.ndarray