Add raster-stretch min-max paint properties

[shobhitg]

Sometimes its necessary to have the fragment pixel values stretched between a min and a max.
These two new parameters achieve it. Leaving them as default will end up not changing anything.

Launch Checklist

• briefly describe the changes in this PR
• write tests for all new functionality
• document any changes to public APIs
• post benchmark scores
• manually test the debug page
• tagged @mapbox/studio and/or @mapbox/maps-design if this PR includes style spec changes
• tagged @mapbox/gl-native if this PR includes shader changes or needs a native port

[shobhitg]

Hello,

The intention in this PR is to mirror a certain layer color enhancement functionality that we have in QGis called Stretch To MinMax.

More details about this Stretch To MinMax can be read here: https://docs.qgis.org/2.8/en/docs/training_manual/rasters/changing_symbology.html

[shobhitg]

The launch checklist says that I should tag @mapbox/studio & @mapbox/gl-native. But I don't see any way to add reviewers. Maybe I don't have permissions.

[andrewharvey]

hi @shobhitg thanks for putting this together.

The raster layer is only really designed for 3 band RGB rasters, in which case there is no need for stretching.

For single band raster with #3889 you'd be able to do stretching by setting a higher minimum and a lower maximum stop.

While I think this is a nice feature to support, and I certainly don't want to be too discouraging, but I do have concerns about how this would work when #3889 is implemented. Having both a raster-stretch when we implement raster colorize, I think raster-stretch would be redundant and cause unnecessary complexity, if anyone was using both at the same time. In that case I think it would be better to rely on raster-colorize to do stretching instead of raster-stetch.

What do you think?

[shobhitg]

For single band raster with #3889 you'd be able to do stretching by setting a higher minimum and a lower maximum stop.

Is there a sample implementation that goes with #3889 ?
If there is, I would be happy to use raster-colorizer.

I feel raster-stretch and raster-colorizer can co-exist very easily. One is about stretching overall brightness min and max, and the other is about manipulating individual color bands. Most clients won't be using both properties together.

[andrewharvey]

Is there a sample implementation that goes with #3889 ?

No, but someone posted a checklist #3889 (comment)

I feel raster-stretch and raster-colorizer can co-exist very easily.

I think they conflict with each other since the results vary based on which is applied first, to which there is no natural answer.

For example if you have a single band raster with values from 0-255 then you can scale it as so
raster-colorizer-stops:
stop(100, black)
stop(200, white);

but if you've also set a scale then does that happen before or after the above? And what does it achieve that raster-colorizer doesn't?

One is about stretching overall brightness min and max, and the other is about manipulating individual color bands. Most clients won't be using both properties together.

There is already a property to alter the brightness, raster-brightness-min and max, https://docs.mapbox.com/mapbox-gl-js/style-spec/#paint-raster-raster-brightness-min, how is this scale-min/max different?

[shobhitg]

I think they conflict with each other since the results vary based on which is applied first, to which there is no natural answer.

I don't entirely understand how raster-colorize works, therefore I am not able to comment of how it can help with the stretching of color intensity.

There is already a property to alter the brightness, raster-brightness-min and max, https://docs.mapbox.com/mapbox-gl-js/style-spec/#paint-raster-raster-brightness-min, how is this scale-min/max different?

raster-brightness-min & raster-brightness-max
is not the same as
raster-stretch-min & raster-stretch-max

I should have given examples earlier.

Doing so now.

This is the original raster tile I am dealing with:

This tile looks very dull, I wish to increase the comfort of looking into it by brightening it up. To brighten up, decreasing raster-brightness-max from 1 (default) won't do any good, instead if I try to bump up raster-brightness-min from 0 (default), then where is what I get:

raster-brightness-min: 0.4

raster-brightness-min: 0.8

Playing with raster-contrast doesn't do much magic either.

*Now compare this with if I decrease raster-stretch-max from 1 (default):
raster-stretch-max: 0.3

Day and night difference.

The above example shows that raster-stretch achieves different goals than raster-brightness.

[shobhitg]

Another example that for the inversely bright tiles.

The original tile is this:

The black lines aren't amazingly clear, and I wish to improve the visibility of dark lines.

The best I could get by a combination of raster-contrast and raster-brightness-min is somewhere around this:
raster-contrast: 0.5
raster-brightness-min: 0.5

And if I try to achieve this by stretching the pixel intensities favoring the darks:
raster-stretch-min: 0.7

[andrewharvey]

I don't entirely understand how raster-colorize works, therefore I am not able to comment of how it can help with the stretching of color intensity.

It would be equivalent to QGIS's Singleband pseudocolor. Ie. you set data values which map to colours.

You could set your own min/max for a singleband raster by setting the lower and upper ramp step values.

here is the histogram of my example, you can see in blue how you could use rasterize to shift the ends of the range, so setting a new min/max.

Thanks for examples on the difference with brightness. I think you could probably do the same by setting the right color stops to shift the histogram.

It's mostly just that I see your proposal here conflicting with raster-colorize. Happy to be proven wrong.

[shobhitg]

Thanks, I will try to experiment with QGIS's Singleband pseudocolor settings to see if the same effect be achieved with it or not.

[shobhitg]

I verify that the same desired effect can be achieved with QGIS's Singleband pseudocolor settings. Therefore in theory, raster-colorize could have achieved it too.

Now only if we had a raster-colorize implementation :)

[asheemmamoowala]

@shobhitg Thanks for this contribution and for using mapbox-gl-js!

I do have concerns about how this would work when #3889 is implemented. Having both a raster-stretch when we implement raster colorize, I think raster-stretch would be redundant and cause unnecessary complexity, if anyone was using both at the same time. In that case I think it would be better to reply on raster-colorize to do stretching instead of raster-stetch.

I agree with @andrewharvey here. raster-colorize would be a more versatile solution to the problem you are trying to solve with this PR. Want to put together a PR for that instead?

[shobhitg]

Want to put together a PR for that instead?

I will give it a shot next month.

[asheemmamoowala]

@shobhitg, given #8587 (comment), I'm going to close this PR for now. When you're ready to work on colorize please reach out with an RFC or plan early for review.