sigmoidalcontrastimage.xml Amend parameter names

[mmalferov]

Integer values in the description are confusing, whereas numbers in the x.xx format seem to be perceived more easily, and the type remains consistent

[kamil-tekiela]

This is still super confusing to me, but I have no idea how to write it better.

[kamil-tekiela]

I don't think dividing by 100 is correct here. I don't know anything about Imagick, so I think keeping it 0, 50, 100 is safer.

[kamil-tekiela]

This page was based on https://phpimagick.com/Imagick/sigmoidalContrastImage?midpoint=0&sigmoidal_contrast=0.5&sharpening=Increase&image_path=Lorikeet so I think we should try to keep it the same as they document it in the official docs.

It looks like we have the contrast and midpoint reversed.

[kamil-tekiela]

Honestly, I think this user note is way better at explaining it than our whole manual page: https://www.php.net/manual/en/imagick.sigmoidalcontrastimage.php#113920

The whole page needs to be rewritten.

[lacatoire]

The 0/50/100 scale comes from the ImageMagick command line, where the mid-point is written as a percentage. Imagick::sigmoidalContrastImage() takes an absolute quantum value instead, so those numbers do not carry over.

Measurement

ImageMagick 7.1.1-43 Q16, Imagick 3.8.1, PHP 8.4. The filter is applied to a gradient:black-white, and the pixel that does not move — the midpoint of the transfer curve — is read back. quantumRangeLong is 65535.

beta passed	reading	midtone
0	raw	0.9870
50	raw	0.9869
100	raw	0.9869
0.0 * QR = 0	fraction	0.9870
0.5 * QR = 32767.5	fraction	0.5050
1.0 * QR = 65535	fraction	0.0136

Raw 0, 50 and 100 are indistinguishable: against a quantum range of 65535 they all mean white. The fraction form gives white, middle-gray and black as documented, and it is the only build-independent form, since getQuantumRange() returns 255 on a Q8 build and 65535 on Q16 — the same literal number would denote a different midtone.

$im = new Imagick();
$im->newPseudoImage(256, 1, 'gradient:black-white');
$im->sigmoidalContrastImage(true, 10.0, $beta);
echo $im->getImagePixelColor(128, 0)->getColorValue(Imagick::COLOR_RED);

The page contradicts itself today

The description says "0 is white; 50 is middle-gray; 100 is black", while the beta entry ten lines below says "range 0 to 1 - multiplied by the quantum value" — which is also the reading the example on the page relies on. Only one of the two can be right, and the measurement above says it is the second.

Parameter order

The signature is sigmoidalContrastImage(bool $sharpen, float $alpha, float $beta, int $channel). Holding beta at 0.5 * QR and raising alpha widens the gradient around that midpoint:

alpha	p25	p75
0	0.2510	0.7529
3	0.2189	0.7851
20	0.0068	0.9937

So alpha is the contrast and beta the mid-point, which is the order both the current page and this PR use.

This PR does not attempt the full rewrite mentioned above; it only corrects the scale and the parameter names. The rewrite is worth a separate issue.