[gdal-dev] Meaning of nPixelSpace/nLineSpace in IRasterIO

[Jorge Arévalo]

Hello,

2011/7/8 Even Rouault <even.rouault at mines-paris.org>:
> Le vendredi 08 juillet 2011 16:09:31, Jorge Arévalo a écrit :
>> Hello,
>>
>> I'm not sure of the meaning of nPixelSpace, nLineSpace IRasterIO args.
>>
>> >From GDAL doc I read:
>> nPixelSpace: The byte offset from the start of one pixel value in
>> pData to the start of the next pixel value within a scanline. If
>> defaulted (0) the size of the datatype eBufType is used.
>>
>> nLineSpace: The byte offset from the start of one scanline in pData to
>> the start of the next. If defaulted (0) the size of the datatype
>> eBufType * nBufXSize is used.
>>
>> and
>>
>> The nPixelSpace and nLineSpace parameters allow reading into or
>> writing from unusually organized buffers. This is primarily used for
>> buffers containing more than one bands raster data in interleaved
>> format.
>>
>> I know there are, basically, 3 interleave formats:
>>
>> BSQ (INTERLEAVE=BAND)
>> BIL (INTERLEAVE=LINE)
>> BIP (INTERLEAVE=PIXEL)
>>
>> Assuming a 3-bands (rgb) 4x4 raster, the pData array would look like
>> this ("|" used only to mark the end of a row):
>>
>> BSQ: r1 r1 r1 r1 | r2 r2 r2 r2 | r3 r3 r3 r3 | r4 r4 r4 r4 | g1 g1 g1
>> g1 | g2 g2 g2 g2 | g3 g3 g3 g3 | g4 g4 g4 g4 g4 | b1 b1 b1 b1 | b2 b2
>> b2 b2 | b3 b3 b3 b3 | b4 b4 b4 b4
>
> For the sake of simplicity, let's assume that the datatype is byte (if not,
> just multiply all values by GDALGetDataType(eDT) / 8),
>
> Yes, nPixelOffset = 1, nLineOffset = nBufferXSize, nBandOffset = nBufferXSize *
> nBufferYSize.
>
> (nBandOffset is for GDALDatasetRasterIO())
>

Ok, understood.


>>
>> BIL: r1 r1 r1 r1 | g1 g1 g1 g1 | b1 b1 b1 b1 | r2 r2 r2 r2 | g2 g2 g2
>> g2 | b2 b2 b2 b2 | r3 r3 r3 r3 | g3 g3 g3 g3 | b3 b3 b3 b3 | r4 r4 r4
>> r4 | g4 g4 g4 g4 | b4 b4 b4 b4
>
> Yes, nPixelOffset = 1, nLineOffset = nBufferXSize * nBands, nBandOffset =
> nBufferXSize
>

Understood.


>>
>> BIP: r1 g1 b1 r2 | g2 b2 r3 g3 | b3 r4 g4 b4 | r1 g1 b1 r2 | g2 b2 r3
>> g3 | b3 r4 g4 b4 | r1 g1 b1 r2 | g2 b2 r3 g3 | b3 r4 g4 b4 | r1 g1 b1
>> r2 | g2 b2 r3 g3 | b3 r4 g4 b4
>
> You meant :
>
> r1 g1 b1 r1 g1 b1 r1 g1 b1 r1 g1 b1 |
> r2 g2 b2 r2 g2 b2 r2 g2 b2 r2 g2 b2 |
> r3 g3 b3 r3 g3 b3 r3 g3 b3 r3 g3 b3 |
> r4 g4 b4 r4 g4 b4 r4 g4 b4 r4 g4 b4 |
>
> right ?
>
> And nPixelOffset = nBands, nLineOffset = nBands * nBufferXSize, nBandOffset = 1
>

Yes, you're right. Understood.


>>
>> Now my doubt.
>>
>> Does "byte offset" mean the byte space between the start of 2 valid
>> values in pData?
>
> The maths will speak better...
>
> If you output buffer starts at address pStart, for band b (numbered from 1) the
> value of the pixel at line j (numbered from 0), column i (numbered from 0) of
> the output buffer will be stored at :
>
> pStart + i * nPixelSpace + j * nLineSpace + (b-1) * nBandSpace
>
> So nPixelSpace is the difference between the address of a pixel and the pixel
> at its right on the same line.
>

Absolutely clear now :-)


>> For example, the space between r1 and g1 in BIP
>> format. I guess if there's no trailing bits in the array (all the bits
>> are payload) the byte offset between the start of 2 valid values is
>> always the size of the data type. Then simply r1 = pData[0] and g1 =
>> pData[1] (BIP format)
>
> Not sure to follow you, hopefully the above explinations will answer your
> question ;-)
>

Don't worry. I understand now. You answered my question, yes.


>>
>> Isn't it the most common situation? In which situation has sense
>> having "gaps" between pixel values, or at the end of a row?
>
> Sometimes you just want to override the values of an allocated buffer with
> greater extent, so you need to provide a so-called "line stride" that is
> greater than nBufferXSize.
>

Ok.


>> I think I
>> don't really understand the sentence: "This is primarily used for
>> buffers containing more than one bands raster data in interleaved
>> format.".
>
> I guess it means that if you need to read from different bands with multiple
> calls to RasterIO() but in the same buffer, you can tweak nPixelSize and
> nLineOffset to let enough space for data from different bands and match the
> organization of the data as you've designed it.
>

Yep, ok. My doubt is already solved. Many thanks!

Best regards,
Jorge

>>
>> Thanks in advance, and best regards.
>> Jorge
>



-- 
Jorge Arévalo
Internet & Mobility Division, DEIMOS
jorge.arevalo at deimos-space.com
http://es.linkedin.com/in/jorgearevalo80
http://mobility.grupodeimos.com/
http://gis4free.wordpress.com
http://geohash.org/ezjqgrgzz0g