[Feature]: `raster.mosaic` matches each input to the one above it in their overlap, and can feather the seam

Open
#2,595 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
30/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
rust
Domain
data

Research direction

Start at the raster.mosaic command: find where inputs are ordered and blended so you can see how "first wins" is applied today, and where per-band data and no-data are handled. Then look at the existing raster.function bandMath and the histogram-matching code referenced as geolibre:histogram_matching_two_images for reusable quantile/CDF fitting. Done means optional match and feather parameters defaulting to today's behaviour, per-band gain/offset reported in the result's matched list, and tests over synthetic overlapping rasters covering the no-overlap notice and the Int16 output type.

Written by the indexing model from the issue text.

Description

Before you start
  • I searched the existing issues and did not find a duplicate (#2585 is about masking dates in cube.reduce; this is about joining scenes of different days).
  • This is a feature request.
What is missing?

raster.mosaic puts inputs together with "the first wins where they overlap". Scenes from different days rarely have the same gain and offset, so the seam shows. Today the user has to measure the overlap elsewhere, then apply raster.function bandMath by hand, then mosaic.

Example (CBERS-4A WPM panchromatic, 2 m, Viçosa-MG; 19/08/2024 on top of 14/08/2024, overlap 42 % of the area):

mean in overlap std. dev. in overlap
19/08 (top) 213.2 42.9
14/08 (below) 216.6 63.8
14/08 × 0.8025 + 41.9 (quantile fit, by hand + bandMath) 215.4 at the seam 46.7 at the seam
14/08 through geolibre:histogram_matching_two_images 215.0 at the seam 44.2 at the seam

The brightness jump at the seam is small (+4 DN of 212); the visible difference is contrast, which the fit removes. geolibre:histogram_matching_two_images matches whole histograms, including the parts that do not overlap, so it cannot be told to use the overlap only.

Proposal

Two optional parameters on raster.mosaic:

raster.mosaic {"inputs": [top, …, bottom], "match": "linear" | "histogram" | "none", "feather": metres}
  • match: each input, from the second down, is fitted to what is already above it in their overlap only (cells valid in both), then mosaicked.
  • feather: across the seam, the lower input fades into the upper one over that distance (distance to the upper input's edge), instead of a hard cut.
Choices in this proposal
  • Default "none" and feather 0: today's results do not change.
  • "linear" fits gain and offset from quantiles 5–95 of the overlap (a line through matched quantiles), not mean and standard deviation: clouds and their shadows in one scene pull the moments, the quantile fit less so. "histogram" maps full CDFs of the overlap, for scenes from different sensors.
  • Fit in the overlap only, per band; with no overlap (or under 1 % of the smaller input), the input is left as it is and a notice says so.
  • The fitted gain and offset are listed in the result ("matched": [{"input": …, "gain": …, "offset": …, "cells": …}]), so a script or plugin can report them.
  • The output keeps the inputs' data type (an Int16 mosaic stays Int16, rounded), with no-data kept; today a bandMath step turns it into Float32.
  • Feathering is linear in distance and uses the valid-data edge of the upper input, not its rectangle (scene edges in these products are diagonal).
Environment

RustGIS 0.7.0 (Windows 11, x64), MCP rustgis-cli.

Dominant language
Rust
Stars
1.9k
Forks
268
Avg merge
11h 1m
Merged PRs (30d)
942

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from opengeos/RustGIS

All issues in opengeos/RustGIS

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.