Functions

2D+time image handlers
[Timelapse Image Representations]

2D+time time-lapse images are represented by "ordinary i3dcore's" 3D image (Image3d<VOXEL>). More...

Functions

template<class VOXEL >
void PutPixel (Image3d< VOXEL > &img, const float x, const float y, const float z, const VOXEL voxel, const char overwrite=0)
template<class VOXEL >
void PutPixelNN (Image3d< VOXEL > &img, const float x, const float y, const float z, const VOXEL voxel, const char overwrite=0)
template<class VOXEL >
int Insert2DFrame (Image3d< VOXEL > const &frame, Image3d< VOXEL > &seq, const int time, const char action=TimeLapseReplace, const int count=1)
template<class VOXEL >
int Copy2DFrame (Image3d< VOXEL > const &seq, Image3d< VOXEL > &frame, const int time)
template<class VOXEL >
int Remove2DFrame (Image3d< VOXEL > &seq, const int time, const int count=1)
template<class VOXEL >
int ReadSequence (i3d::Image3d< VOXEL > &seq, const char *NamePrefix, const int Width, const char *NameSuffix, const int StartIndex, const int StopIndex)
template<class VOXEL >
int SaveSequence (i3d::Image3d< VOXEL > const &seq, const char *NamePrefix, const int Width, const char *NameSuffix, const int StartIndex, const int StopIndex)
template<class VOXEL >
int InsertGroupOfLines (Image3d< VOXEL > &seq, const float vx, const float vy, const int delta_t, const float gx, const float gy, const int gt, const float lx=0.0f, const float ly=10.0f, const float spacing=2.0f, const int number=10, const VOXEL color=static_cast< VOXEL >(250))

Detailed Description

2D+time time-lapse images are represented by "ordinary i3dcore's" 3D image (Image3d<VOXEL>).

The time axis, t-axis, supersedes the z-axis. The image remains xyz technically while it is xyt officially.

Function Documentation

template<class VOXEL >
void PutPixel ( Image3d< VOXEL > &  img,
const float  x,
const float  y,
const float  z,
const VOXEL  voxel,
const char  overwrite = 0 
)

Spread the value to the nearest 4 or 8 (8 if GetSizeZ() > 1) voxels.

Example of the spreading schema involved for 2D situation: 

 *  Let |,-,+ denote borders between adjacent voxels.
 *  Let . denote an outline of the voxel given by real coordinate.
 *  Let x denote the real-valued coordinate (the centre of the voxel outlined with .).
 *  Let o denote the nearest integer coordinate to the x coordinate.
 *
 *  +-----------+-----------+
 *  | 2         |        1  |
 *  |  .............        |
 *  |  .  o     |  .        |   -------- integer line
 *  |  .        |  .        |
 *  |  .  B  x  |A .        |
 *  +--.--------+--.--------+
 *  |  .  C     |D .        |
 *  |  .............        |
 *  |           |           |   -------- integer line
 *  |           |           |
 *  | 3         |         4 |
 *  +-----------+-----------+
 *
 *        |           |
 *        |           |
 *        |           |
 *        ------------------------------ integer line
 *

Normally, the interger-valued center x would be positioned in the center of, let's say, voxel 2 (see lines along integer-valued coordinates) and the whole value will be stored in the voxel 2. Instead, in this situation only portion A of the inserted value should be stored in voxel 1, portion B in the voxel 2, etc. All portions, summed up alltogether, sum up to exactly the inserted value. Hence, we will split the value according to the areas A, B, C and D and store it in the voxels 1, 2, 3 and 4, respectively.

The PutPixel function should actually add given voxel since several real-positioned voxels can contribute to the respective integer-valued positions. This is the behaviour of the function when the overwrite parameter is set to 0 (zero), this is the default. Otherwise (non-zero overwrite parameter), the voxel value is directly assigned regardless of a previous value at the given position (x,y,z).

Parameters:
[in,out] img image to be modified
[in] x real-valued x-position of the inserted voxel
[in] y real-valued y-position of the inserted voxel
[in] z real-valued z-position of the inserted voxel
[in] voxel inserted voxel value
[in] overwrite controls whether an inserted value should be just added to the values already present in the image img or not
Note:
This is a helper function to the InsertGroupOfLines(). It is not officially visible outside the library at the moment (= it is not manifested in the header file). However, anyone can access this function after explicitly specifying its declaration in his/her source code.
Author:
Vladimír Ulman (xulman@fi.muni.cz)
Date:
2007
template<class VOXEL >
void PutPixelNN ( Image3d< VOXEL > &  img,
const float  x,
const float  y,
const float  z,
const VOXEL  voxel,
const char  overwrite = 0 
)

Set the value to the nearest voxel.

The PutPixel function should actually add given voxel since several real-positioned voxels can contribute to the respective integer-valued positions. This is the behaviour of the function when the overwrite parameter is set to 0 (zero). Otherwise (non-zero overwrite parameter), the voxel value is directly assigned regardless of a previous value at the given position (x,y,z).

Parameters:
[in,out] img image to be modified
[in] x real-valued x-position of the inserted voxel
[in] y real-valued y-position of the inserted voxel
[in] z real-valued z-position of the inserted voxel
[in] voxel inserted voxel value
[in] overwrite controls whether an inserted value should be just added
Note:
This is a helper function to the InsertGroupOfLines(). It is not officially visible outside the library at the moment (= it is not manifested in the header file). However, anyone can access this function after explicitly specifying its declaration in his/her source code.
Author:
Vladimír Ulman (xulman@fi.muni.cz)
Date:
2007
template<class VOXEL >
int Insert2DFrame ( Image3d< VOXEL > const &  frame,
Image3d< VOXEL > &  seq,
const int  time,
const char  action = TimeLapseReplace,
const int  count = 1 
)

A 2D frame image is inserted into a "sequence" image.

This function replaces, inserts or adds a new frame into the sequence at the position according to the parameters time and action. If action is:

  • TimeLapseInit: the sequence image is first released (original image data will be lost!) and then new image is allocated; its dimensions are: xy are the values of xy of the frame image, t (dimension along z-axis) is given by the parameter time; the new image is initialized by zeros
  • TimeLapseInsert: insert the count copies of frame at the position time, all consequent frames are "renumbered" (i.e. shifted in t by plus count) including the original frame at time; the sequence image will be enlarged
  • TimeLapseReplace: replace the frame at position time; this a default action, parameter count is ignored
  • TimeLapseAppend: adds count many copies of the frame at the end of the sequence, to add just one frame set count to 1; the sequence image will be enlarged, parameter time is ignored
Parameters:
[in] frame input frame to be inserted
[in,out] seq "sequence image" to be modified
[in] time position (time slot, frame no.) where to include the new frame
[in] action meaning of the time parameter
[in] count the number of repetitions of selected action

Only the 0th slice of image frame is used, even when count > 1 (when copy of first count slices could have been expected).

Note:
Due to memory handling in cases where sequence lenght changes, it is generally better to resize the image at once, eventually followed by several frame replacements instead of insertions or additions.

To insert 3 frames into the sequence, the following code may useful: 

 * Insert2DFrame(frame1,seq,time1,TimeLapseInsert,3);	//enlarge the 2D sequence along z (time-axis)
 * 							//temporary sequence backup was needed, slow
 * Insert2DFrame(frame2,seq,time2);			//"insert" the second frame, TimeLapseReplace is the default action
 * 							//no backup of sequence, efficient with memory
 * Insert2DFrame(frame3,seq,time3);			//"insert" the third frame
 *

Or, to append 3 frames into the sequence: 

 * Insert2DFrame(frame1,seq,-1,TimeLapseAppend,3);	//enlarge the 2D sequence image z (time-axis)
 * 							//temporary sequence backup was needed, slow
 * Insert2DFrame(frame2,seq,time2);			//"append" the second frame, TimeLapseReplace is the default action
 *							//no backup of sequence, efficient with memory
 * Insert2DFrame(frame3,seq,time3);			//"append" the third frame
 *

Attention! The function returns exactly -1 whenever some problem occured. When everything went well, the starting frame index (time position) of modified image is returned, thus the zero or any other possitive value signify OK status.

template<class VOXEL >
int Copy2DFrame ( Image3d< VOXEL > const &  seq,
Image3d< VOXEL > &  frame,
const int  time 
)

A frame image is copied from the "sequence" image seq.

The "sequence" image has the same meaning as in the previous function, refer to its description. Only 2D time-lapse sequences are handled by this function. The frames are numbered from zero with zero denoting the first frame. The original content in the output image frame is lost, the image is resized according to the dimensions of sequence image seq.

Parameters:
[in,out] seq "sequence image" to be modified
[out] frame the target image to which selected frame is copied
[in] time time slot to be copied out

It returns non-zero whenever some problem occured, else zero is returned.

template<class VOXEL >
int Remove2DFrame ( Image3d< VOXEL > &  seq,
const int  time,
const int  count = 1 
)

This function removes given count frames from the sequence image seq and "renumbers" the following frames, i.e.

the rest of the image is shifted by count frame towards the begining. The frame to be removed is given by the parameter time (time-position of the frame). The resulting sequence image is shorten by count. The default value for count is 1.

Parameters:
[in,out] seq "sequence image" to be modified
[in] time the first time slot to be removed
[in] count the number of time slots to be removed

Returns zero when everything went well.

template<class VOXEL >
int ReadSequence ( i3d::Image3d< VOXEL > &  seq,
const char *  NamePrefix,
const int  Width,
const char *  NameSuffix,
const int  StartIndex,
const int  StopIndex 
)

Reads sequence of images into a 2D sequence.

The specification of filenames is composed to this example:

to read files: green_0001.tif to green_0012.tif is translated into: ReadSequence(seq,"green_",4,".tif",1,12);

Parameters:
[out] seq the "sequence" image to load into
[in] NamePrefix the part of filename before the index number
[in] Width the width of zero-padded index number in the filename
[in] NameSuffix the part of filename after the index number
[in] StartIndex the first index number
[in] StopIndex the last index number

All processed images should be of the same dimension and have the same metadata.

Parameters StartIndex and StopIndex are relevant only to filenames. A new 2D "sequence" image is always created. It has an appropriate length and frames are stored at positions (slices) starting with 0 (zero).

template<class VOXEL >
int SaveSequence ( i3d::Image3d< VOXEL > const &  seq,
const char *  NamePrefix,
const int  Width,
const char *  NameSuffix,
const int  StartIndex,
const int  StopIndex 
)

Stores 2D sequence into several files.

The specification of filenames is according to this example:

to save files: green_0001.tif to green_0012.tif is translated into: SaveSequence(seq,"green_",4,".tif",1,12);

Parameters:
[in] seq the "sequence" image to save from
[in] NamePrefix the part of filename before the index number
[in] Width the width of zero-padded index number in the filename
[in] NameSuffix the part of filename after the index number
[in] StartIndex the first index number
[in] StopIndex the last index number

All saved images will be of the same dimension and will have the same metadata.

Parameters StartIndex and StopIndex are relevant both to filenames and indices within the sequence of frames. In other words, only a subsequence can be saved owing to the two parameters.

template<class VOXEL >
int InsertGroupOfLines ( Image3d< VOXEL > &  seq,
const float  vx,
const float  vy,
const int  delta_t,
const float  gx,
const float  gy,
const int  gt,
const float  lx = 0.0f,
const float  ly = 10.0f,
const float  spacing = 2.0f,
const int  number = 10,
const VOXEL  color = static_cast< VOXEL >(250) 
)

This function modifies existing 2D "sequence" image (in fact, 3D image = xy image + time).

It draws a moving group of several lines into the sequence. The group is organized as a set of parallel equally-spaced and equally-oriented lines. The top left corner of the group is the starting point of the first line. The direction in which the line is drawn depends on the input parameters as well as the drawing of consequent lines depends on the sign of the spacing parameter.

The movement, position and description of the group is encoded in the parameters of this function (descripted in the order in which they appear in the parameter list):

Parameters:
[in,out] seq the "sequence image" to which we draw

the movement related parameters:

Parameters:
[in] vx,vy velocity vector (encompases direction and the speed)
[in] delta_t the number of frames for which the movement should last

the initial position related parameters:

Parameters:
[in] gx,gy,gt spatiotemporal position of the top left corner of the group

the group shape related parameters:

Parameters:
[in] lx,ly the direction vector of each line in the group (the length of the vector equals the length of each line)
[in] spacing the distance between adjacent lines, the distance is measured in the direction perpendicular to the lines vector
[in] number the number of lines in the group
[in] color the voxel intensity used to draw the lines

The function returns non-zero value on error. Zero is returned otherwise.

Generated on Tue Mar 8 2011 18:22:44 for The CBIA Optic Flow by  doxygen 1.7.1