Author: Cinly OOI (---.psychiatry.cam.ac.uk)
Date: 10-08-08 08:46
Dear Rick,
Thanks for the explanation in both emails. Obviously, I had misunderstood what nifti_image_write_NBL() does.
I was using nifti_image_load_bricks() the way it intended, i.e., I don't want nim to be changed. So I am OK I guess, unless you are going to change the function of nifti_image_load_bricks to match that of nifti_image_read_bricks().
I read the the API description for nifti_image_read_bricks() from the website's pub subdirectory and notice two things which I think some clarification is needed:
(1)it is mentioned that the returned nifti_image structure is the same as that of nifti_image_read(), which it is not, since dim[4] = NBL->nbricks which is not the same as the original dim[4], if blist is supplied.
(2)Second, I think in first paragraph you meant
and not " list of nt[*nu*nv*nw] sub-bricks, each having size nx*ny*nz elements.", i.e. delete [...]
(3)In the example, I believe B_orig.nbricks = 12, not 11 since we have 12 subbricks, not 11.
Below is the proposed revision of the API information for your consideration. Additions are marked with <add>...</add> and deletion <del>...</del>
/*----------------------------------------------------------------------*/
/*! nifti_image_read_bricks - read nifti data as array of bricks <add reason="taste & clarifying what a brick is">of 3D data</add>
*
* 13 Dec 2004 [rickr]
*
* \param hname - filename of dataset to read (must be valid)
* \param nbricks - number of sub-bricks to read
* (if blist is valid, nbricks must be > 0)
* \param blist - list of sub-bricks to read
* (can be NULL; if NULL, read complete dataset)
* \param NBL - pointer to empty nifti_brick_list struct
* (must be a valid pointer)
*
* \return
* <br> nim - same as nifti_image_read, but nim->data will be NULL
* <add> and nim->dim[4] = NBL->nbricks</add>
* <br> NBL - filled with data
*
* <del reason="taste: cannot see why is this 'default' behaviour. Rather, we are describing two possible operation mode here">By default</del><add>If 'blist' is NULL, </add>this function will read the nifti dataset and break the data
* into a list of nt<del>*nu*nv*nw</del> sub-bricks, each having size nx*ny*nz elements.
* That is to say, instead of reading the entire dataset as a single array,
* break it up into sub-bricks, each of size nx*ny*nz elements.
*
* If 'blist' is not NULL, it is taken to be a list of <add>indices for the subbricks required (zero-indexed)</add> <del>sub-bricks,</del> <add>.This list must be </add> of length
* 'nbricks'. The data will still be separated into sub-bricks of size
* nx*ny*nz elements, but now 'nbricks' sub-bricks will be returned, of the
* caller's choosing via 'blist' <add>and the returned nifti_image structures's dim[4] set to 'nbricks'</add>
*
* E.g. consider a dataset with 12 sub-bricks (numbered 0..11), and the
* following code:
*
* <pre>
* { nifti_brick_list NB_orig, NB_select;
* nifti_image * nim_orig, * nim_select;
* int blist[5] = { 7, 0, 5, 5, 9 };
*
* nim_orig = nifti_image_read_bricks("myfile.nii", 0, NULL, &NB_orig);
* nim_select = nifti_image_read_bricks("myfile.nii", 5, blist, &NB_select);
* }
* </pre>
*
* Here, nim_orig gets the entire dataset, where NB_orig.nbricks = <del>11</del><add>12</add>. <add>nim_orig->dim[4] = 12 since the whole dataset is written</add> But
* nim_select has NB_select.nbricks = 5 <add>nim_select->dim[4] = 5 since only 5 sub-bricks were read</add>
*
* Note that the first case is not quite the same as just calling the
* nifti_image_read<add reason"clarification: this function use the second parameter to decide whether to read data or not.">(hname, 1)</add> function, as here the data <add>not written to nim->data but </add> is separated into sub-bricks <add>and written to NBL->bricks</add>.
*
* Note that valid blist elements are in [0..nt*nu*nv*nw-1],
* or written [ 0 .. (dim[4]*dim[5]*dim[6]*dim[7] - 1) ].
*
* Note that, as is the case with all of the reading functions, the
* data will be allocated, read in, and properly byte-swapped, if
* necessary.
*
* \sa nifti_image_load_bricks, nifti_free_NBL, valid_nifti_brick_list,
nifti_image_read
*//*----------------------------------------------------------------------*/
Thanks and HTH
Cinly
|
|
