Precinct switch (-c) doesn't right-shift last record to remaining resolution levels

[bitsgalore]

Just ran across a small issue with the -c parameter. Suppose I want to create a JP2 with precincts, with a precinct size of 256 for the two highest resolution levels, and 128 for the remaining resolution levels. The opj_compress help message says:

Multiple records may be supplied, in which case the first record refers
to the highest resolution level and subsequent records to lower
resolution levels. The last specified record is right-shifted for each
remaining lower resolution levels.

So this should work (I'm using v2.3.0):

opj_compress -i foo.tif -o foo.jp2 -n 6 -c [256,256],[256,256],[128,128]

But if I check the precinct sizes in foo.jp2 with jpylyzer I get this:

<precinctSizeX>16</precinctSizeX>
<precinctSizeY>16</precinctSizeY>
<precinctSizeX>32</precinctSizeX>
<precinctSizeY>32</precinctSizeY>
<precinctSizeX>64</precinctSizeX>
<precinctSizeY>64</precinctSizeY>
<precinctSizeX>128</precinctSizeX>
<precinctSizeY>128</precinctSizeY>
<precinctSizeX>256</precinctSizeX>
<precinctSizeY>256</precinctSizeY>
<precinctSizeX>256</precinctSizeX>
<precinctSizeY>256</precinctSizeY>

So instead of right-shifting the last specified record to all remaining resolution levels, opj_compress successively halves that value for each remaining level.

Of course a simple workaround here is to explicitly set the precinct size for each resolution level:

opj_compress -i foo.tif -o foo.jp2 -n 6 -c [256,256],[256,256],[128,128],[128,128],[128,128],[128,128]

Result:

<precinctSizeX>128</precinctSizeX>
<precinctSizeY>128</precinctSizeY>
<precinctSizeX>128</precinctSizeX>
<precinctSizeY>128</precinctSizeY>
<precinctSizeX>128</precinctSizeX>
<precinctSizeY>128</precinctSizeY>
<precinctSizeX>128</precinctSizeX>
<precinctSizeY>128</precinctSizeY>
<precinctSizeX>256</precinctSizeX>
<precinctSizeY>256</precinctSizeY>
<precinctSizeX>256</precinctSizeX>
<precinctSizeY>256</precinctSizeY>

Which is as expected.

[boxerab]

The help message means to say that the precincts for successive resolutions after last specified are right shifted (halved) successively. The text may be ambiguous, but the library is performing as specified. So, perhaps the message could be made clearer.

[bitsgalore]

@boxerab You're right, I wasn't aware the help message actually refers to a bitwise arithmetic shift (I do wonder how many non-developer users are familiar with this).

[boxerab]

@bitsgalore I agree, "division by two" should probably be used instead of the shift terminology. You could open an issue for this if the spirit moves you. Or better, a pull request :)