[Kst] Matrixes and datasources

[Rick Chern]

On Mon, 2005-08-08 at 20:37 +0200, Barth Netterfield wrote:
> I am trying to understand how we are supposed to read matrixes through data 
> sources.... and I see that the ascii data source appears to support it.   Who 
> wrote this, and is there an example data file with a matrix in it?

The ascii data source implementation for reading matrices was mostly for
testing purposes only, but it does demonstrate the matrix reading
interface of KstDataSource.  There is a sample data file
tests/asciimatrix.txt

> 
> Other questions:
> If you have a file with 1 matrix in it:
> 	what should num frames be? (I assume 1)
> 	what should samples per frame be (not defined?)

- frameCount() should return the number of cells in the matrix in total
- samplesPerFrame() should return the number of samples per cell of the
matrix (each cell of the matrix can have more than one sample - at first
there was no concept of frames for matrices but from discussion on the
bug report 108025, frames and samples were added).

> 	
> What do the following comments mean in kstdatasource.h:
> 
>     /** Read the specified sub-range of the matrix, flat-packed in z in 
> row-major order (non-skipping)
>         xStart - starting x *frame*
>         yStart - starting y *frame*
>         xNumSteps - number of *frames* to read in x direction; -1 to read 1 
> *sample* from xStart
>         yNumSteps - number of *frames* to read in y direction; -1 to read 1 
> *sample* from yStart
>         The suggested scaling and translation is returned in xMin, yMin, 
> xStepSize, and yStepSize
>         Returns the number of *samples* read **/

I guess using "frames" and "samples" was not clear here, but a frame is
a cell of the matrix, and a sample is a sample within a cell.  

As an example, to read the submatrix starting at cell (2,3) and ending
at cell (4,4), the following would be passed to the above function:
xStart = 2 
yStart = 3
xNumSteps = 2
yNumSteps = 1

Each matrix has a location on the x-y grid and each cell of the matrix
is a rectangle with x and y dimensions.  Unlike before, these values are
specified by the datasource and not by the user.  

Reading a submatrix should return approprate (xMin, yMin) and xStepSize,
yStepSize to specify the subrange of the submatrix within the full
matrix in x-y space.

In the above example, if the full matrix had a starting coordinate of
(3.5, 2.5) and each cell has xStepSize = 0.5 and yStepSize = 1.0, then
reading the above submatrix would return:
xMin = 3.5+2*0.5 = 4.5
yMin = 2.5+3*1.0 = 5.5
xStepSize = 0.5
yStepSize = 1.0

The above values are returned in the struct KstMatrixData* data.