Skip to main content

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.

warning

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.

OperationSet withRead with
A lookup table of your ownSetUserColorValues()GetUserColorValues()
Brightness, as an offsetSetColorTableBrightness()GetColorTableBrightness()
Gamma, on the mid-tonesSetGamma()GetGamma()
White balance, from a colour that should read as greySetWhiteBalanceBrightness()GetWhiteBalanceBrightness()
Contrast, around a fixed pivotSetContrast()GetContrast()
InversionSetNegative()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:

OperationTarget distributionSet with
EqualizationUniformSetHistogramEqualization()
FitThe shape of a histogram you supplySetHistogramFit()
NormalizationGaussian, with a mean and standard deviationSetHistogramNormalization()

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.

note

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:

SettingInitial value
Colour-table processingDisabled
Filter operationEFPO_NO_FILTER
Brightness, contrast0
Gamma1
White-balance reference(0, 0, 0), no correction
Negativefalse
Equalization, fit, normalizationfalse
Visible-area histogramOff

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().

  • 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.

Verified against MapCore 12.5.0

Written from Map/IMcImageProcessing.h, Map/IMcRasterMapLayer.h, Map/IMcMapViewport.h, McCommonTypes.h