[jafin]

Prerequisites

• I have written a descriptive pull-request title
• I have verified that there are no overlapping pull-requests open
• I have verified that I am following the existing coding patterns and practice as demonstrated in the repository. These follow strict Stylecop rules 👮.
• I have provided test coverage for my change (where applicable)

Description

Problem

The decoder handled a maxval other than 255 or 65535 in two steps:

1. It converted the raw samples to the destination pixel type.
2. It ran a Brightness pass over the whole image.

Step 2 happened after any loss of precision in step 1. A 16-bit sample with a small maxval was narrowed to 8 bits before it was scaled. As a result, decoding to an 8-bit pixel type, such as Rgb24 (the default for Image.Load), kept only a few distinct levels. For example, with maxval 1000:

• Sample 500 decoded to 131 instead of about 128.
• Sample 7 decoded to 0 instead of 2.
• The image had only five gray levels.

Change

• The plain and binary decoders now scale each sample from [0, maxval] to the full 8-bit or 16-bit range before they convert the row to the pixel type.
• The scaling uses rounded integer arithmetic. maxval maps exactly to the full value, and samples above maxval are clamped.
• The new PbmSampleScaler.Scale method does the scaling for both decoders.
• The binary decoder skips the scaling step when maxval already covers the full range.
• The Brightness pass over the decoded image is removed. Images with a non-standard maxval now need one pass less.

Testing

The new theory Decode_NonStandardMaxPixelValue_ScalesSamplesToByteRange in PbmDecoderTests covers P2, P3, P5 and P6 with maxval 100 and 1000. It decodes to Rgb24 and compares each component with round(sample * 255 / maxval), with a tolerance of one step. The test inputs are built in memory.

On main, the four maxval 1000 cases fail and the maxval 100 cases pass. With this change, all eight cases pass.

I ran all tests in the Pbm namespace in Release on net10.0: 121 passed. These include the existing reference-image comparisons for maxval 15 inputs and the round-trip tests.

Fixes #3239