BUG: decoding planar confusion about openjph HOT 6 CLOSED

Hi Pierre,

Thank you for putting this in.

if a color transform is used, planar must be false
if downsampling is used, planar must be true.
otherwise, planar is at the choice of the client

All correct.

In planar is true, which is easier to explain with YUV, first codestream.pull() produce Y for as many Y rows in the image, then, U for as many U rows, then V.

When planar is false, which is easier to explain with RGB, first codestream.pull() produce a row of R, second pull produce a row of G, third 'B', and so on.

The parameter comp_num in codestream.pull(comp_num), which is an output parameter, tells you to which component the pulled line belongs.

The following code, taken from ojph_expand, might help explain this.

  if (codestream.is_planar())
    {
      ojph::param_siz siz = codestream.access_siz();
      for (ojph::ui32 c = 0; c < siz.get_num_components(); ++c)
      {
        ojph::ui32 height = siz.get_recon_height(c);
        for (ojph::ui32 i = height; i > 0; --i)
        {
          ojph::ui32 comp_num;
          ojph::line_buf *line = codestream.pull(comp_num);
          assert(comp_num == c);
          base->write(line, comp_num);
        }
      }
    }
    else
    {
      ojph::param_siz siz = codestream.access_siz();
      ojph::ui32 height = siz.get_recon_height(0);
      for (ojph::ui32 i = 0; i < height; ++i)
      {
        for (ojph::ui32 c = 0; c < siz.get_num_components(); ++c)
        {
          ojph::ui32 comp_num;
          ojph::line_buf *line = codestream.pull(comp_num);
          assert(comp_num == c);
          base->write(line, comp_num);
        }
      }
    }

Notice where the color loop is and also notice the assert statement.

Kind regards,
Aous.

from openjph.

Hi Chris,

Thank you for putting this in. I just realized that the term might be confusing. The ultimate objective is not to needlessly buffer lines in the library.

The idea is that if there is no color transform, it is more efficient for the encoder/decoder to process one color component at a time; this is what I call planar because each color plane is fed in sequentially, one line at a time, before the following component's plane. This is the only option available if some color components are downsampled.

If a color transform is used, which requires all the components to have the same downsampling ratio, then the library expects to receive a line from first component, then second, then third, before moving back to the first; this allows the library to perform the color transform. This is what I am calling not-planar (planar = false). This option is also available if no color transform is needed, but it should be less computationally efficient, by a small amount, because it is more likely to have cache evictions.

A line always carries on color component.

I agree that my terminology is not conventional, but I was not very sure how to handle this.

Kind regards,
Aous

from openjph.

The use of planar in this context is confusing, it should be changed or at least documented in the header file. While your explanation is helpful, I am still unsure what it returns when decoding a set_planar(true). Does the output depend on whether or not a color transform is applied? The only HTJ2K color image I have right now is lena from subprojects/js/html/test.j2c.

from openjph.

If color transform is required, set_planar(true) will generate a error message. If color transform is not needed, then set_planar(true) should work fine.

Color transform is required, if it is set in the corresponding marker, and the file has three color components, and they all have the same downsampling ratio.

from openjph.

OK think I understand now, thanks for the clarification!

from openjph.

@aous72 To summarize from the point of view of a client using the decoder:

• if a color transform is used, planar must be false
• if downsampling is used, planar must be true
• otherwise, planar is at the choice of the client

planar controls whether codestream.pull() outputs RRR...RRRGGG...GGGBBB...BBB (true) or RGBRGB...RGBRGB (false), where each R, G, B` means one line.

Correct (or not)?

from openjph.