[Insight-developers] Doc updates for ImageIOBase
Steve M. Robbins
steve at sumost.ca
Fri Jan 2 19:25:52 EST 2009
Thanks so much to Luis for patiently answering my questions in this
thread. I believe that I understand the semantics of ImageIOBase
quite a bit better now.
I've used my new understanding to revise the doxygen comments in
itkImageIOBase.h. The patch (against CVS head) is attached.
I would propose to commit this, but not until I get the go-ahead from
someone at Kitware. I'd appreciate other developers looking this over
for accuracy and style.
You'll notice two "TODO: Deprecate?" comments. I don't propose to
commit these. However, neither WriteImageInformation() nor
m_Initialized can reliably be used in the code base today. So what
should one do about them?
Any comments welcome.
Thanks,
-Steve
-------------- next part --------------
Index: Code/IO/itkImageIOBase.h
===================================================================
RCS file: /cvsroot/Insight/Insight/Code/IO/itkImageIOBase.h,v
retrieving revision 1.49
diff -u -b -B -r1.49 itkImageIOBase.h
--- Code/IO/itkImageIOBase.h 25 Jun 2008 11:30:38 -0000 1.49
+++ Code/IO/itkImageIOBase.h 3 Jan 2009 00:21:09 -0000
@@ -39,10 +39,31 @@
* ImageSeriesReader and ImageSeriesWriter classes are used to read
* and write data (in conjunction with ImageIOBase) when the data is
* represented by a series of files. Normally the user does not directly
- * manipulate this class other than to instantiate it, set the FileName,
+ * manipulate this class other than to instantiate it
* and assign it to a ImageFileReader/ImageFileWriter or
* ImageSeriesReader/ImageSeriesWriter.
*
+ * An image consists of pixel values together with associated metadata
+ * such as that describing the image sampling grid location in a
+ * global or world reference space; e.g. the origin, spacing, and
+ * directions. Note that the world space coordinate system is right
+ * handed and, when dealing with medical images, uses the LPS
+ * convention; i.e. that the positive X-, Y-, and Z-axes in world
+ * space point towards the patient Left, Posterior, and Superior
+ * (head), respectively. If metadata present in the file uses a
+ * different convention, it will be converted.
+ *
+ * In order to read image data, the caller must first set the file
+ * name using SetFileName() then call the method
+ * ReadImageInformation(). At this point the image information is
+ * available using methods such as GetSpacing(). To read the pixel
+ * data, the caller must first call SetIORegion() and then Read().
+ *
+ * When used to write image data, the caller must first set up the
+ * image information using methods such as SetSpacing(),
+ * SetFileName(), etc. Next, invoke the method SetIORegion() followed
+ * by Write().
+ *
* A Pluggable factory pattern is used this allows different kinds of readers
* to be registered (even at run time) without having to modify the
* code in this class.
@@ -66,7 +87,7 @@
/** Run-time type information (and related methods). */
itkTypeMacro(ImageIOBase, Superclass);
- /** Set/Get the name of the file to be read. */
+ /** Set/Get the name of the file to be read or written. */
itkSetStringMacro(FileName);
itkGetStringMacro(FileName);
@@ -91,36 +112,50 @@
ULONG,LONG, FLOAT,DOUBLE} IOComponentType;
/** Set/Get the number of independent variables (dimensions) in the
- * image being read or written. Note this is not necessarily what
- * is written, rather the IORegion controls that. */
+ * image being read or written. Note that the region of data read or
+ * written is controlled by calling SetIORegion() and may not be the
+ * full image.
+ */
void SetNumberOfDimensions(unsigned int);
itkGetMacro(NumberOfDimensions, unsigned int);
- /** Set/Get the image dimensions in the x, y, z, etc. directions.
+ /** Set/Get the image dimension (number of samples) along the i'th axis.
* GetDimensions() is typically used after reading the data; the
- * SetDimensions() is used prior to writing the data. */
+ * SetDimensions() is used prior to writing the data.
+ */
virtual void SetDimensions(unsigned int i, unsigned int dim);
virtual unsigned int GetDimensions(unsigned int i) const
{ return m_Dimensions[i]; }
- /** Set/Get the image origin on a axis-by-axis basis. The SetOrigin() method
- * is required when writing the image. */
+ /** Set/Get the i'th image-space coordinate value of the image origin.
+ * The SetOrigin() method is required when writing the image.
+ */
virtual void SetOrigin(unsigned int i, double origin);
virtual double GetOrigin(unsigned int i) const
{
return m_Origin[i];
}
- /** Set/Get the image spacing on an axis-by-axis basis. The
- * SetSpacing() method is required when writing the image. */
+ /** Set/Get the world-space distance between adjacent samples along
+ * the i'th axis. The SetSpacing() method is required when writing
+ * the image. Medical images measure spacing in millimetres.
+ */
virtual void SetSpacing(unsigned int i, double spacing);
virtual double GetSpacing(unsigned int i) const
{
return m_Spacing[i];
}
- /** Set/Get the image direction on an axis-by-axis basis. The
- * SetDirection() method is required when writing the image. */
+ /** Set/Get the world-space direction of the i'th axis. Each axis
+ * direction is a d-dimensional unit vector, where d =
+ * GetNumberOfDimensions(). The world space uses right-handed
+ * coordinate system and, for medical images, the LPS convention;
+ * i.e. that the positive X-, Y-, and Z-axes in world space point
+ * towards the patient Left, Posterior, and Superior (head),
+ * respectively.
+ *
+ * The SetDirection() method is required when writing the image.
+ */
virtual void SetDirection(unsigned int i, std::vector<double> &direction);
virtual void SetDirection(unsigned int i, vnl_vector<double> &direction);
virtual std::vector<double> GetDirection(unsigned int i) const
@@ -128,55 +163,66 @@
return m_Direction[i];
}
- /** Specify the region of the image data to either read or
- * write. The IORegion specifies the part of the image to read or
- * write. Regions are defined with an index and a size vector. These
- * vectors define the start (lower-left corner) and length of the
- * region within the image. Make sure that the IORegion lies within
- * the image. */
+ /** Specify the IORegion, which is the region of the image data
+ * to either read or write. Regions are defined with an index and a
+ * size vector. These vectors define the start (lower-left corner)
+ * and length of the region within the image. The caller must ensure
+ * that the IORegion lies within the image.
+ */
itkSetMacro(IORegion, ImageIORegion);
itkGetConstMacro(IORegion, ImageIORegion);
- /** Set/Get the type of the pixel. The PixelTypes provides context
- * to the IO mechanisms for data conversions. PixelTypes can be
+ /** Set/Get the type of the pixel present in the buffer provided to
+ * functions Read() and Write(). PixelTypes can be
* SCALAR, RGB, RGBA, VECTOR, COVARIANTVECTOR, POINT, INDEX. If
* the PIXELTYPE is SCALAR, then the NumberOfComponents should be 1.
- * Anyother of PIXELTYPE will have more than one component. */
+ * Any other PIXELTYPE will have more than one component. */
itkSetEnumMacro(PixelType, IOPixelType);
itkGetEnumMacro(PixelType, IOPixelType);
- /** SetPixelTypeInfo is used by writers to convert from an ITK
- * strongly typed pixel to a ImageIO (weaker) typed pixel. This
- * function sets these PixelType, ComponentType, and
- * NumberOfComponents based on RTTI type_info structure passed
- * in. The function returns false if the pixel type is not
- * supported. */
+ /** Equivalent to calling SetPixelType(), SetComponentType() and
+ * SetNumberOfComponents(). The function returns false if the pixel
+ * type is not supported. */
virtual bool SetPixelTypeInfo(const std::type_info& ptype);
- /** Set/Get the component type of the image. This is always a native
- * type. */
+ /** Set/Get the component type of the image. For a scalar pixel,
+ * this is the type of the pixel; otherwise it is the type used for
+ * each element in the pixel. It is always a native
+ * type.
+ *
+ * This is the type used for pixel data in methods Read() and
+ * Write(). It is typically the same type as the data on disk;
+ * however, it may be different if the disk file specifies a
+ * transformation of pixel values such as a slope/intercept pair or
+ * a scalar-to-rgb lookup table.
+ */
itkSetEnumMacro(ComponentType,IOComponentType);
itkGetEnumMacro(ComponentType,IOComponentType);
virtual const std::type_info& GetComponentTypeInfo() const;
- /** Set/Get the number of components per pixel in the image. This may
- * be set by the reading process. For SCALAR pixel types,
+ /** Set/Get the number of components per pixel in the image.
+ * For SCALAR pixel types,
* NumberOfComponents will be 1. For other pixel types,
* NumberOfComponents will be greater than or equal to one. */
itkSetMacro(NumberOfComponents,unsigned int);
itkGetConstReferenceMacro(NumberOfComponents,unsigned int);
- /** Set/Get a boolean to use the compression or not. */
+ /** Set/Get a boolean indicating whether to use compression. Some
+ * subclasses use this, some ignore it. */
itkSetMacro(UseCompression,bool);
itkGetConstReferenceMacro(UseCompression,bool);
itkBooleanMacro(UseCompression);
- /** Set/Get a boolean to use streaming while reading or not. */
+ /** Set/Get a boolean indicating whether to use streaming while
+ * reading. Some subclasses use this, some ignore it.
+ * \sa CanStreamRead()
+ */
itkSetMacro(UseStreamedReading,bool);
itkGetConstReferenceMacro(UseStreamedReading,bool);
itkBooleanMacro(UseStreamedReading);
- /** Set/Get a boolean to use use streaming while writing or not. */
+ /** Set/Get a boolean indicating whether to use use streaming while
+ * writing. Some subclasses use this, some ignore it. */
itkSetMacro(UseStreamedWriting,bool);
itkGetConstReferenceMacro(UseStreamedWriting,bool);
itkBooleanMacro(UseStreamedWriting);
@@ -243,8 +289,8 @@
/** Type for representing size of bytes, and or positions along a file */
typedef std::streamoff SizeType;
- /** Convenient method for accessing the number of bytes to get to
- * the next pixel. Returns m_Strides[1]; */
+ /** Return the number of bytes to get to
+ * the next pixel in an image buffer. */
virtual SizeType GetPixelStride () const;
/** Return the number of pixels in the image. */
@@ -257,47 +303,76 @@
* of components in the image. */
SizeType GetImageSizeInComponents() const;
- /*-------- This part of the interfaces deals with reading data ----- */
+ /*-------- This part of the interface deals with reading data ----- */
- /** Determine the file type. Returns true if this ImageIO can read the
+ /** Returns true if this ImageIO can read the
* file specified. */
virtual bool CanReadFile(const char*) = 0;
- /** Determine if the ImageIO can stream reading from this
- file. Default is false. */
+ /** Return true if the ImageIO can stream reading from this
+ * file. The method ReadImageInformation() must be called
+ * prior to calling CanStreamRead().
+ *
+ * Any subclass that can potentially stream reads must
+ * implement this function.
+ *
+ * \sa SetUseStreamedReading()
+ */
virtual bool CanStreamRead()
{
return false;
}
- /** Read the spacing and dimentions of the image.
- * Assumes SetFileName has been called with a valid file name. */
+ /** Read the spacing, dimensions and other metadata of the image.
+ * Assumes SetFileName has been called with a valid file name.
+ * After this call, methods such as GetDimension(), GetSpacing(),
+ * etc will return the correct values.
+ */
virtual void ReadImageInformation() = 0;
- /** Reads the data from disk into the memory buffer provided. */
+ /** Reads the data from disk into the memory buffer provided. The
+ * caller must first call ReadImageInformation() and SetIORegion().
+ * The buffer provided must be correctly sized for the IORegion
+ * desired and considering the pixel and component types; c.f.
+ * GetPixelSize().
+ *
+ * The buffer is populated in the same ordering (i.e. XYZ, XZY, etc)
+ * as in the disk file.
+ */
virtual void Read(void* buffer) = 0;
- /*-------- This part of the interfaces deals with writing data ----- */
+ /*-------- This part of the interface deals with writing data ----- */
- /** Determine the file type. Returns true if this ImageIO can read the
+ /** Return true if this ImageIO can write the
* file specified. */
virtual bool CanWriteFile(const char*) = 0;
- /** Determine if the ImageIO can stream writing to this
- file. Default is false. */
+ /** Return true if the ImageIO can stream writing to this
+ * file.
+ *
+ * Any subclass that can potentially stream writes must
+ * implement this function.
+ */
virtual bool CanStreamWrite()
{
return false;
}
- /** Writes the spacing and dimentions of the image.
- * Assumes SetFileName has been called with a valid file name. */
+ // TODO: Deprecate? This method is not used in ITK code and only 2 subclasses implement it.
+ /** Write the spacing, dimensions and other metadata of the image.
+ * Assumes SetFileName has been called with a valid file name.
+ */
virtual void WriteImageInformation() = 0;
- /** Writes the data to disk from the memory buffer provided. Make sure
- * that the IORegions has been set properly. The buffer is cast to a
- * pointer to the beginning of the image data. */
+ /** Writes the data to disk, both pixel (provided in the given
+ * buffer) and other metadata. The caller must first call
+ * SetIORegion() to specify the image region to write.
+ *
+ * The buffer provided must be correctly sized for the IORegion
+ * desired and considering the pixel and component types; c.f.
+ * GetPixelSize().
+ */
virtual void Write( const void* buffer) = 0;
/* --- Support reading and writing data as a series of files. --- */
@@ -305,8 +380,12 @@
/** The different types of ImageIO's can support data of varying
* dimensionality. For example, some file formats are strictly 2D
* while others can support 2D, 3D, or even n-D. This method returns
- * true/false as to whether the ImageIO can support the dimension
- * indicated. */
+ * true if the ImageIO can support the dimension
+ * indicated.
+ *
+ * Any subclass that supports dimensions other than 2 must
+ * implement this function.
+ */
virtual bool SupportsDimension(unsigned long dim)
{
return (dim == 2);
@@ -315,9 +394,10 @@
/** Method for supporting streaming. Given a requested region, determine what
* could be the region that we can read from the file. This is called the
* streamable region, which will be smaller than the LargestPossibleRegion and
- * greater or equal to the RequestedRegion */
+ * greater or equal to requestedRegion
+ */
virtual ImageIORegion
- GenerateStreamableReadRegionFromRequestedRegion( const ImageIORegion & requested ) const;
+ GenerateStreamableReadRegionFromRequestedRegion( const ImageIORegion & requestedRegion ) const;
/** Type for the list of strings to be used for extensions. */
typedef std::vector< std::string > ArrayOfExtensionsType;
@@ -343,14 +423,14 @@
/** Used internally to keep track of the type of the pixel. */
IOPixelType m_PixelType;
- /** Used internally to keep track of the type of the component. It is set
- * when ComputeStrides() is invoked. */
+ /** Used internally to keep track of the type of the component. */
IOComponentType m_ComponentType;
/** Big or Little Endian, and the type of the file. (May be ignored.) */
ByteOrder m_ByteOrder;
FileType m_FileType;
+ // TODO: Deprecate? Set to false in Reset() and never used anywhere else.
/** Does the ImageIOBase object have enough info to be of use? */
bool m_Initialized;
@@ -402,6 +482,7 @@
const unsigned int* dimensions);
/** Calculates the different strides (distance from one thing to the next).
+ * The component size and dimensions must be set before calling this.
* Upon return,
* strides[0] = bytes to get to the next component of a pixel,
* strides[1] = bytes to get to the next pixel in x direction,
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <http://www.itk.org/mailman/private/insight-developers/attachments/20090102/79f745dd/attachment.pgp>
More information about the Insight-developers
mailing list