Process raster imagery
Scanned maps arrive too dark, orthophotos from two sources do not match, a sharpening pass makes detail readable at a scale where it was not. All of that is display-side work: the pixels on disk are untouched, and the same layer can look different in two viewports at once.
Interface for image processing of raster imagery in a viewport (inherited by IMcMapViewport).
Every method operates either on a single raster layer (pLayer points to the layer) or on the whole viewport image (pLayer is NULL, applied as a full-screen post-process covering the background and all map layers - raster, vector, etc. - but not objects). A layer passed as pLayer must belong to one of the viewport's terrains, including a layer whose initialization has not finished yet. All settings are per viewport: they do not affect other viewports showing the same layer, and per-layer settings are discarded when the layer is removed from the viewport.
There are two independent processing mechanisms:
- A per-channel color lookup table combining, in application order: user color values, brightness, gamma, white balance, contrast, histogram fit, histogram equalization, histogram normalization and negative. It is applied only while enabled by SetEnableColorTableImageProcessing().
- A convolution filter (see SetFilterImageProcessing()), which is applied regardless of the above.
The color-table and histogram methods work per channel (EColorChannel): ECC_MULTI_CHANNEL sets all three channels at once and, in getters, succeeds only when the three hold the same value.
Used for:
- The filter: SetFilterImageProcessing() / GetFilterImageProcessing() select one of the predefined smoothing and sharpening kernels or EFPO_CUSTOM_FILTER, whose kernel SetCustomFilter() / GetCustomFilter() hold.
- The color table: SetEnableColorTableImageProcessing() / GetEnableColorTableImageProcessing() switch it on and off; SetUserColorValues(), GetUserColorValues(), SetColorValuesToDefault() and GetCurrentColorValues() work with the lookup table itself; SetWhiteBalanceBrightness(), SetColorTableBrightness(), SetContrast(), SetGamma() and SetNegative(), with their getters, set the value adjustments, and SetHistogramEqualization(), SetHistogramFit() and SetHistogramNormalization(), with theirs, the histogram-based ones.
- Histograms: SetOriginalHistogram() / GetOriginalHistogram() and IsOriginalHistogramSet() supply the reference histogram the histogram operations start from, SetVisibleAreaOriginalHistogram() / GetVisibleAreaOriginalHistogram() have it recomputed from the visible tiles instead, and GetCurrentHistogram() estimates the histogram of the processed image.
See also: IMcMapViewport, IMcMapViewport::SetBrightness()
— from Map/IMcImageProcessing.h
You call these methods on a viewport, because IMcMapViewport inherits this interface. The first
argument of every one of them is the target rather than a filter: a layer, or NULL for the whole
viewport image.
Sharpen or smooth with a filter
The filter is the simpler of the two mechanisms, and the independent one. It runs whether or not the colour table is enabled, so a sharpening pass needs nothing else switched on:
pViewport->SetFilterImageProcessing(pLayer, IMcImageProcessing::EFPO_SHARP_MID);
Six of the eight EFilterProcessingOperation values are built-in kernels, in low, mid and high
strengths of smoothing and sharpening. EFPO_NO_FILTER is the initial state. The eighth,
EFPO_CUSTOM_FILTER, applies a kernel of your own:
float aKernel[9] = { 0, -1, 0,
-1, 5, -1,
0, -1, 0 };
pViewport->SetCustomFilter(pLayer, 3, 3, aKernel, 0.0f, 1.0f);
pViewport->SetFilterImageProcessing(pLayer, IMcImageProcessing::EFPO_CUSTOM_FILTER);
The order of those two calls does not matter. A kernel set while another operation is selected is
stored and takes effect when EFPO_CUSTOM_FILTER is next selected. GetCustomFilter() reads back
the kernel, bias and divider; GetFilterImageProcessing() reads back the operation.
In C++ the kernel is a bare pointer and the function reads uFilterXsize × uFilterYsize values
from it. An array shorter than the sizes you declare is read past its end, and nothing detects it.
The .NET, Java and Web APIs carry the array length and reject the call instead. Both dimensions are
capped at 9.
Enhance with the colour table
Everything else runs through one per-channel lookup table, and nothing in it is visible until the master switch is on:
pViewport->SetGamma(pLayer, IMcImageProcessing::ECC_MULTI_CHANNEL, 1.2);
pViewport->SetContrast(pLayer, IMcImageProcessing::ECC_MULTI_CHANNEL, 0.3);
pViewport->SetEnableColorTableImageProcessing(pLayer, true);
Configuring first and enabling last is deliberate and supported: while the switch is off the individual settings are still stored and still readable, they simply have no visual effect. That makes the switch a usable before-and-after toggle, and it means a layer that looks unprocessed is not evidence that the settings did not take.
| Operation | Set with | Read with |
|---|---|---|
| A lookup table of your own | SetUserColorValues() | GetUserColorValues() |
| Brightness, as an offset | SetColorTableBrightness() | GetColorTableBrightness() |
| Gamma, on the mid-tones | SetGamma() | GetGamma() |
| White balance, from a colour that should read as grey | SetWhiteBalanceBrightness() | GetWhiteBalanceBrightness() |
| Contrast, around a fixed pivot | SetContrast() | GetContrast() |
| Inversion | SetNegative() | GetNegative() |
The three histogram operations belong to the same table and are covered below.
GetCurrentColorValues() returns the single table all of them combine into, which is the one thing
that answers "what is actually being applied" without reasoning about the pipeline.
SetColorValuesToDefault() resets a channel, keeping only the original histogram.
Channels, and when a getter fails
ECC_MULTI_CHANNEL is not symmetric. As a setter it writes red, green and blue together. As a
getter it succeeds only when all three already agree, and returns IMcErrors::INVALID_PARAMETERS
when they do not. So a getter that worked during development can start failing as soon as someone
tunes one channel on its own. Read a specific channel when the three are not known to match.
Histograms
Histogram equalization, fit and normalization all remap intensities relative to a reference distribution, so none of them does anything until that reference exists. Setting one without a reference is not an error: the setting is stored and simply has no effect, which is the usual reason an equalization that "does nothing" is not doing nothing wrong.
There are two ways to supply the reference.
Compute it once from the layer. IMcRasterMapLayer::CalcHistogram() fills one histogram per
channel from a sampled level of detail, and those go straight in:
MC_HISTOGRAM aHistogram[3];
pLayer->CalcHistogram(aHistogram);
pViewport->SetOriginalHistogram(pLayer, IMcImageProcessing::ECC_RED, aHistogram[0]);
pViewport->SetOriginalHistogram(pLayer, IMcImageProcessing::ECC_GREEN, aHistogram[1]);
pViewport->SetOriginalHistogram(pLayer, IMcImageProcessing::ECC_BLUE, aHistogram[2]);
Only the shape matters; the counts are normalized internally. GetOriginalHistogram() reads it back
and IsOriginalHistogramSet() reports whether a channel has one.
Or let the visible area supply it. SetVisibleAreaOriginalHistogram() recomputes the reference
from the tiles currently on screen, every time that set changes, so the enhancement follows the map
as the user pans and zooms. For a layer it uses that layer's tiles; for the whole viewport it
combines every visible raster layer by transparency. Turning the mode off restores whatever
SetOriginalHistogram() had supplied, and clears the reference if nothing had. Note that this mode
runs only while colour-table processing is enabled, and that IsOriginalHistogramSet() and
GetOriginalHistogram() both ignore the automatic histogram and report the explicitly set one.
GetVisibleAreaOriginalHistogram() reports whether the mode is on.
With a reference in place, the three operations are:
| Operation | Target distribution | Set with |
|---|---|---|
| Equalization | Uniform | SetHistogramEqualization() |
| Fit | The shape of a histogram you supply | SetHistogramFit() |
| Normalization | Gaussian, with a mean and standard deviation | SetHistogramNormalization() |
Each has its getter: GetHistogramEqualization(), GetHistogramFit() and
GetHistogramNormalization(). GetCurrentHistogram() estimates the histogram of the processed
image, which is what a before-and-after display needs.
GetHistogramNormalization() reports a mean and standard deviation of 0 before the first call to
its setter, not the 127.5 and 42.5 that the setter's own parameters default to. Feeding a reported
0 back into an enabled normalization fails, because the standard deviation must be above 0 when
bUse is true.
What the defaults are
Nothing here is on until you turn it on:
| Setting | Initial value |
|---|---|
| Colour-table processing | Disabled |
| Filter operation | EFPO_NO_FILTER |
| Brightness, contrast | 0 |
| Gamma | 1 |
| White-balance reference | (0, 0, 0), no correction |
| Negative | false |
| Equalization, fit, normalization | false |
| Visible-area histogram | Off |
Performance and scope
Settings are per viewport. Two viewports showing one layer process it independently, and per-layer settings are discarded when the layer leaves the viewport. They are not part of the layer, so they are not saved with it.
Visible-area mode recomputes on every change to the visible tile set. That is what makes it
track the map, and it is also its cost. Where the imagery is uniform enough, computing a reference
once with CalcHistogram() is cheaper.
Not every rendering system supports this. On OpenGL with a driver below version 3, the filter
calls succeed and do nothing, and GetFilterImageProcessing() always reports EFPO_NO_FILTER while
GetCustomFilter() reports zero sizes and a NULL kernel. Code that trusts a returned
IMcErrors::SUCCESS as proof of a visible change will be wrong on those systems.
A layer that has not finished initialising is still a valid target. Passing one is accepted, so
processing can be configured at the same time as the layer is created, without waiting for
IMcMapLayer::IReadCallback::OnInitialized().
Related
- Add a raster layer covers
CalcHistogram()and the layers this applies to. IMcMapViewport::SetBrightness()is a separate, whole-stage brightness that does not go through this interface.