KisAutoLevels Namespace Reference

This namespace contains functions to compute the levels adjustment parameters automatically from a histogram. More...

Classes
struct	ChannelHistogram
	Convenience class that associates a KisHistogram and a channel index. This is useful because setting a channel on the histogram mutates it. This way the functions can change the histogram channel by looking at the "channel" field. More...

Enumerations
enum	MidtonesAdjustmentMethod { MidtonesAdjustmentMethod_None , MidtonesAdjustmentMethod_UseMedian , MidtonesAdjustmentMethod_UseMean }
	The different methods to enhance the mid tones. More...
enum	ShadowsAndHighlightsAdjustmentMethod { ShadowsAndHighlightsAdjustmentMethod_MonochromaticContrast , ShadowsAndHighlightsAdjustmentMethod_PerChannelContrast }
	The different methods to enhance the contrast. More...

Functions
QVector< KisLevelsCurve >	adjustMonochromaticContrast (ChannelHistogram lightnessHistogram, QVector< ChannelHistogram > &channelsHistograms, qreal shadowsClipping, qreal highlightsClipping, qreal maximumInputBlackAndWhiteOffset, MidtonesAdjustmentMethod midtonesAdjustmentMethod, qreal midtonesAdjustmentAmount, const QVector< qreal > &outputBlackPoints, const QVector< qreal > &outputWhitePoints, const QVector< qreal > &outputMidtones)
	Creates a KisLevelsCurve for every channel in "channelsHistograms". Computes the input black and white points from the intensity histogram. Computes the gamma from each channels histogram and "outputMidtones" if the method is not "None". The output black and white points are computed from "outputBlackPoints" and "outputWhitePoints".
QVector< KisLevelsCurve >	adjustPerChannelContrast (QVector< ChannelHistogram > &channelsHistograms, qreal shadowsClipping, qreal highlightsClipping, qreal maximumInputBlackAndWhiteOffset, MidtonesAdjustmentMethod midtonesAdjustmentMethod, qreal midtonesAdjustmentAmount, const QVector< qreal > &outputBlackPoints, const QVector< qreal > &outputWhitePoints, const QVector< qreal > &outputMidtones)
	Creates a KisLevelsCurve for every channel in "channelsHistograms". Computes the input black and white points from each channels histogram separately. Computes the gamma from each channels histogram and "outputMidtones" if the method is not "None". The output black and white points are computed from "outputBlackPoints" and "outputWhitePoints".
QPair< KoColor, KoColor >	getDarkestAndWhitestColors (const KisPaintDeviceSP device, qreal shadowsClipping, qreal highlightsClipping)
	Finds the darkest and whitest colors in the device having into account the clipping.
qreal	getGamma (qreal blackPoint, qreal whitePoint, qreal inputIntensity, qreal outputIntensity)
	Computes a gamma value that "moves" the input midpoint towards the output midpoint.
QPair< qreal, qreal >	getInputBlackAndWhitePoints (ChannelHistogram histogram, qreal shadowsClipping, qreal highlightsClipping)
	Takes a reference histogram (luma, lightness) and computes the black and white points to maximize the contrast having into account the clipping.
QPair< qreal, qreal >	getMeanAndMedian (ChannelHistogram histogram, qreal begin, qreal end)

Detailed Description

This namespace contains functions to compute the levels adjustment parameters automatically from a histogram.

Enumeration Type Documentation

MidtonesAdjustmentMethod

enum KisAutoLevels::MidtonesAdjustmentMethod

The different methods to enhance the mid tones.

Enumerator
MidtonesAdjustmentMethod_None
MidtonesAdjustmentMethod_UseMedian
MidtonesAdjustmentMethod_UseMean

Definition at line 39 of file KisAutoLevels.h.

                              {
    MidtonesAdjustmentMethod_None,
    MidtonesAdjustmentMethod_UseMedian,
    MidtonesAdjustmentMethod_UseMean
};

ShadowsAndHighlightsAdjustmentMethod

enum KisAutoLevels::ShadowsAndHighlightsAdjustmentMethod

The different methods to enhance the contrast.

Enumerator
ShadowsAndHighlightsAdjustmentMethod_MonochromaticContrast
ShadowsAndHighlightsAdjustmentMethod_PerChannelContrast

Definition at line 31 of file KisAutoLevels.h.

                                          {
    ShadowsAndHighlightsAdjustmentMethod_MonochromaticContrast,
    ShadowsAndHighlightsAdjustmentMethod_PerChannelContrast
};

Function Documentation

adjustMonochromaticContrast()

QVector< KisLevelsCurve > KRITAIMAGE_EXPORT KisAutoLevels::adjustMonochromaticContrast	(	ChannelHistogram	lightnessHistogram,
		QVector< ChannelHistogram > &	channelsHistograms,
		qreal	shadowsClipping,
		qreal	highlightsClipping,
		qreal	maximumInputBlackAndWhiteOffset,
		MidtonesAdjustmentMethod	midtonesAdjustmentMethod,
		qreal	midtonesAdjustmentAmount,
		const QVector< qreal > &	outputBlackPoints,
		const QVector< qreal > &	outputWhitePoints,
		const QVector< qreal > &	outputMidtones )

Creates a KisLevelsCurve for every channel in "channelsHistograms". Computes the input black and white points from the intensity histogram. Computes the gamma from each channels histogram and "outputMidtones" if the method is not "None". The output black and white points are computed from "outputBlackPoints" and "outputWhitePoints".

Parameters

lightnessHistogram	histogram to compute the input black and white points from
channelsHistograms	list of histograms to compute the gammas from. This is also used to know the number of output levels infos
shadowsClipping	A normalized percentage that is used to know how many samples should be clipped on the shadows side of the histogram by the input black point
highlightsClipping	A normalized percentage that is used to know how many samples should be clipped on the highlights side of the histogram by the input white point
maximumInputBlackAndWhiteOffset	A maximum value for the input black and white points. The black point won't be greater than this, and the white point won't be lesser than 1 - this
midtonesAdjustmentMethod	The method used to get the gamma
midtonesAdjustmentAmount	The strength of the midtone adjustment
outputBlackPoints	The output black points used in each levels info
outputWhitePoints	The output white points used in each levels info
outputMidtones	The desired output midtone values for the gamma adjustment

Returns

A list of levels infos containing parameters for the levels adjustment

Definition at line 138 of file KisAutoLevels.cpp.

{
    Q_ASSERT(lightnessHistogram.histogram);
    Q_ASSERT(lightnessHistogram.channel >= 0);
    Q_ASSERT(lightnessHistogram.channel < lightnessHistogram.histogram->producer()->channels().size());
    Q_ASSERT(outputBlackPoints.size() == channelsHistograms.size());
    Q_ASSERT(outputWhitePoints.size() == channelsHistograms.size());
    Q_ASSERT(outputMidtones.size() == channelsHistograms.size());
 
    QVector<KisLevelsCurve> levelsCurves;
 
    const QPair<qreal, qreal> inputBlackAndWhitePoints =
        getInputBlackAndWhitePoints(lightnessHistogram, shadowsClipping, highlightsClipping);
    const qreal inputBlackPoint = qMin(maximumInputBlackAndWhiteOffset, inputBlackAndWhitePoints.first);
    const qreal inputWhitePoint = qMax(1.0 - maximumInputBlackAndWhiteOffset, inputBlackAndWhitePoints.second);
    const qreal linearMappingMidPoint = (inputBlackPoint + inputWhitePoint) / 2.0;
 
    for (int i = 0; i < channelsHistograms.size(); ++i) {
        ChannelHistogram &channelHistogram = channelsHistograms[i];
            
        qreal gamma = 1.0;
        if (midtonesAdjustmentMethod != MidtonesAdjustmentMethod_None &&
            channelHistogram.histogram &&
            channelHistogram.channel >= 0 &&
            channelHistogram.channel < channelHistogram.histogram->producer()->channels().size()) {
 
            qreal inputIntensity;
            QPair<qreal, qreal> meanAndMedian = getMeanAndMedian(channelHistogram, inputBlackPoint, inputWhitePoint);
 
            if (midtonesAdjustmentMethod == MidtonesAdjustmentMethod_UseMean) {
                inputIntensity = meanAndMedian.first;
            } else {
                inputIntensity = meanAndMedian.second;
            }
 
            inputIntensity = linearMappingMidPoint + (inputIntensity - linearMappingMidPoint) * midtonesAdjustmentAmount;
            gamma = getGamma(inputBlackPoint, inputWhitePoint, inputIntensity, outputMidtones[i]);
        }
 
        levelsCurves.append(
            KisLevelsCurve(
                inputBlackPoint,
                inputWhitePoint,
                gamma,
                outputBlackPoints[i],
                outputWhitePoints[i]
            )
        );
    }
 
    return levelsCurves;
}

References KisAutoLevels::ChannelHistogram::channel, KoHistogramProducer::channels(), getGamma(), getInputBlackAndWhitePoints(), getMeanAndMedian(), KisAutoLevels::ChannelHistogram::histogram, MidtonesAdjustmentMethod_None, MidtonesAdjustmentMethod_UseMean, and KisHistogram::producer().

adjustPerChannelContrast()

QVector< KisLevelsCurve > KRITAIMAGE_EXPORT KisAutoLevels::adjustPerChannelContrast	(	QVector< ChannelHistogram > &	channelsHistograms,
		qreal	shadowsClipping,
		qreal	highlightsClipping,
		qreal	maximumInputBlackAndWhiteOffset,
		MidtonesAdjustmentMethod	midtonesAdjustmentMethod,
		qreal	midtonesAdjustmentAmount,
		const QVector< qreal > &	outputBlackPoints,
		const QVector< qreal > &	outputWhitePoints,
		const QVector< qreal > &	outputMidtones )

Creates a KisLevelsCurve for every channel in "channelsHistograms". Computes the input black and white points from each channels histogram separately. Computes the gamma from each channels histogram and "outputMidtones" if the method is not "None". The output black and white points are computed from "outputBlackPoints" and "outputWhitePoints".

Parameters

channelsHistograms	list of histograms to compute the gammas from. This is also used to know the number of output levels infos
shadowsClipping	A normalized percentage that is used to know how many samples should be clipped on the shadows side of the histogram by the input black point
highlightsClipping	A normalized percentage that is used to know how many samples should be clipped on the highlights side of the histogram by the input white point
maximumInputBlackAndWhiteOffset	A maximum value for the input black and white points. The black point won't be greater than this, and the white point won't be lesser than 1 - this
midtonesAdjustmentMethod	The method used to get the gamma
midtonesAdjustmentAmount	The strength of the midtone adjustment
outputBlackPoints	The output black points used in each levels info
outputWhitePoints	The output white points used in each levels info
outputMidtones	The desired output midtone values for the gamma adjustment

Returns

A list of levels infos containing parameters for the levels adjustment

Definition at line 200 of file KisAutoLevels.cpp.

{
    QVector<KisLevelsCurve> levelsCurves;
 
    for (int i = 0; i < channelsHistograms.size(); ++i) {
        QVector<ChannelHistogram> channelHistogram{channelsHistograms[i]};
        levelsCurves.append(
            adjustMonochromaticContrast(
                channelHistogram[0],
                channelHistogram,
                shadowsClipping,
                highlightsClipping,
                maximumInputBlackAndWhiteOffset,
                midtonesAdjustmentMethod,
                midtonesAdjustmentAmount,
                {outputBlackPoints[i]},
                {outputWhitePoints[i]},
                {outputMidtones[i]}
            )
        );
    }
 
    return levelsCurves;
}

References adjustMonochromaticContrast().

getDarkestAndWhitestColors()

QPair< KoColor, KoColor > KRITAIMAGE_EXPORT KisAutoLevels::getDarkestAndWhitestColors	(	const KisPaintDeviceSP	device,
		qreal	shadowsClipping,
		qreal	highlightsClipping )

Finds the darkest and whitest colors in the device having into account the clipping.

Returns

A pair containing the "darkest" and "lighter" colors

getGamma()

qreal KRITAIMAGE_EXPORT KisAutoLevels::getGamma	(	qreal	blackPoint,
		qreal	whitePoint,
		qreal	inputIntensity,
		qreal	outputIntensity )

Computes a gamma value that "moves" the input midpoint towards the output midpoint.

Parameters

blackPoint	If this gamma value will be part of a more complex levels adjustment, set its black point here. Set it to 0 otherwise. Since the gamma correction is applied after the linear mapping given by the black and white points in a levels adjustment, you have to provide those here to get the correct gamma
whitePoint	same as with blackPoint but for the white point
inputIntensity	This is the intensity value that we want to map to the output value. Sensible values are the mean and the median
outputIntensity	This is the intensity value to which the input value will be mapped to after the gamma correction. Use 0.5 to neutralize the midtones

Returns

the gamma value that, when applied after the linear mapping given by the black and white points, will map the input intensity to the output intensity

Definition at line 119 of file KisAutoLevels.cpp.

{
    Q_ASSERT(blackPoint < whitePoint);
    Q_ASSERT(inputIntensity >= blackPoint && inputIntensity <= whitePoint);
    
    if (qFuzzyIsNull(outputIntensity)) {
        return 0.01;
    }
    if (qFuzzyCompare(outputIntensity, 1.0)) {
        return 10.0;
    }
 
    const qreal inputIntensityAfterLinearMapping =
        (inputIntensity - blackPoint) / (whitePoint - blackPoint);
 
    return qBound(0.01, log(inputIntensityAfterLinearMapping) / log(outputIntensity), 10.0);
}

References qFuzzyCompare(), and qFuzzyIsNull().

getInputBlackAndWhitePoints()

QPair< qreal, qreal > KRITAIMAGE_EXPORT KisAutoLevels::getInputBlackAndWhitePoints	(	ChannelHistogram	histogram,
		qreal	shadowsClipping,
		qreal	highlightsClipping )

Takes a reference histogram (luma, lightness) and computes the black and white points to maximize the contrast having into account the clipping.

Returns

A pair containing the black and white points indices

Definition at line 54 of file KisAutoLevels.cpp.

{
    Q_ASSERT(histogram.histogram);
    Q_ASSERT(histogram.channel >= 0 && histogram.channel < histogram.histogram->producer()->channels().size());
 
    histogram.histogram->setChannel(histogram.channel);
 
    int numberOfBins = histogram.histogram->producer()->numberOfBins();
 
    Q_ASSERT(numberOfBins > 1);
 
    const qreal totalNumberOfSamples = static_cast<qreal>(histogram.histogram->producer()->count());
 
    // This basically integrates the probability mass function given by the
    // histogram, from the left and the right, until the thresholds given by the
    // clipping are reached, to obtain the black and white points
 
    int blackPoint = 0;
    qreal accumulator = 0.0;
    for (int i = 0; i < numberOfBins; ++i) {
        const qreal sampleCountForBin = static_cast<qreal>(histogram.histogram->getValue(i));
        const qreal probability = sampleCountForBin / totalNumberOfSamples;
 
        accumulator += probability;
        if (accumulator > shadowsClipping) {
            break;
        }
        blackPoint = i;
    }
 
    int whitePoint = numberOfBins - 1;
    accumulator = 0.0;
    for (int i = numberOfBins - 1; i >= 0; --i) {
        const qreal sampleCountForBin = static_cast<qreal>(histogram.histogram->getValue(i));
        const qreal probability = sampleCountForBin / totalNumberOfSamples;
 
        accumulator += probability;
        if (accumulator > highlightsClipping) {
            break;
        }
        whitePoint = i;
    }
 
    if (whitePoint <= blackPoint) {
        if (blackPoint + 1 == numberOfBins) {
            whitePoint = blackPoint;
            --blackPoint;
        } else {
            whitePoint = blackPoint + 1;
        }
    }
 
    return
        {
            static_cast<qreal>(blackPoint) / static_cast<qreal>(numberOfBins),
            static_cast<qreal>(whitePoint) / static_cast<qreal>(numberOfBins)
        };
}

References KisAutoLevels::ChannelHistogram::channel, KoHistogramProducer::channels(), KoHistogramProducer::count(), KisHistogram::getValue(), KisAutoLevels::ChannelHistogram::histogram, KoHistogramProducer::numberOfBins(), KisHistogram::producer(), and KisHistogram::setChannel().

getMeanAndMedian()

QPair< qreal, qreal > KisAutoLevels::getMeanAndMedian	(	ChannelHistogram	histogram,
		qreal	begin,
		qreal	end )

Definition at line 18 of file KisAutoLevels.cpp.

{
    Q_ASSERT(histogram.histogram);
    Q_ASSERT(histogram.channel >= 0 && histogram.channel < histogram.histogram->producer()->channels().size());
 
    histogram.histogram->setChannel(histogram.channel);
 
    const int numberOfBins = histogram.histogram->producer()->numberOfBins();
    const int beginBin = static_cast<int>(begin * static_cast<qreal>(numberOfBins));
    const int endBin = static_cast<int>(end * static_cast<qreal>(numberOfBins)) + 1;
 
    qreal numberOfSamples = 0.0;
    qreal meanSum = 0.0;
 
    for (int i = beginBin; i < endBin; ++i) {
        const qreal current = static_cast<qreal>(histogram.histogram->getValue(i));
        numberOfSamples += current;
        meanSum += current * static_cast<qreal>(i);
    }
 
    const qreal mean = meanSum / (numberOfSamples * static_cast<qreal>(numberOfBins));
    qreal probabilityAccumulator = 0.0;
    qreal median = 0.0;
 
    for (int i = beginBin; i < endBin; ++i) {
        const qreal probability = static_cast<qreal>(histogram.histogram->getValue(i)) / numberOfSamples;
        probabilityAccumulator += probability;
        if (probabilityAccumulator >= 0.5) {
            median = static_cast<qreal>(i) / static_cast<qreal>(numberOfBins);
            break;
        }
    }
 
    return {mean, median};
}

References KisAutoLevels::ChannelHistogram::channel, KoHistogramProducer::channels(), KisHistogram::getValue(), KisAutoLevels::ChannelHistogram::histogram, KoHistogramProducer::numberOfBins(), KisHistogram::producer(), and KisHistogram::setChannel().