# HG changeset patch # User magedrifaat # Date 1662560858 -7200 # Node ID ddbed40b811badeaaabe88c8159044576d0d380b # Parent f1c1efd356c82ef8d2f83992d7f58fecae8c3907 Tiff: added documentation for all class methods * scripts/io/Tiff.m: added documentation for all class methods to enable using help and print_usage on the class and its methods. diff -r f1c1efd356c8 -r ddbed40b811b scripts/io/Tiff.m --- a/scripts/io/Tiff.m Tue Sep 06 21:50:48 2022 +0200 +++ b/scripts/io/Tiff.m Wed Sep 07 16:27:38 2022 +0200 @@ -1,4 +1,38 @@ classdef Tiff + + ## -*- texinfo -*- + ## @deftypefn {} {@var{t} =} Tiff (@var{filename}) + ## @deftypefnx {} {@var{t} =} Tiff (@var{filename}, @var{mode}) + ## Open a TIFF image file + ## + ## Open the TIFF image file @var{filename} in file mode @var{mode}. If + ## @var{mode} is not provided, the file is opened for reading. Both + ## @var{filename} and @var{mode} must be strings. + ## + ## The @var{mode} parameter can be one of the following options: + ## + ## @table @asis + ## @item @qcode{"r"} + ## Open file for reading. + ## + ## @item @qcode{"w"} + ## Open file for writing and discard existing data. + ## + ## @item @qcode{"a"} + ## Open or create file for appending. + ## + ## @item @qcode{"w8"} + ## Open BigTIFF file for writing and discard existing data. + ## + ## @item @qcode{"r+"} + ## Open exisiting file for both reading and writing. + ## + ## @end table + ## + ## The return value @var{t} is an object of the Tiff class. + ## @seealso{imread, imwrite} + ## @end deftypefn + properties (Constant = true) TagID = __tiff_make_tagid__ (); @@ -130,138 +164,570 @@ methods function t = Tiff (filename, mode="r") if (nargin == 0 || nargin > 2) - % print_usage(); - error("Usage: Tiff(filename[, mode])"); + print_usage("Tiff"); endif t.tiff_handle = __open_tiff__ (filename, mode); endfunction function close (t) + + ## -*- texinfo -*- + ## @deftypefn {} Tiff.close () + ## Close the TIFF file opened by this object. + ## @end deftypefn + __close_tiff__ (t.tiff_handle); endfunction function tag = getTag (t, tag_name) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{tag} =} Tiff.getTag (@var{tag_id}) + ## @deftypefnx {} {@var{tag} =} Tiff.getTag (@var{tag_name}) + ## + ## Get the value of a tag in the image identified by either its ID + ## number @var{tag_id} or its name @var{tag_name}. + ## + ## To get the ID of a known tag use the @code{Tiff.TagID} structure. + ## + ## An example for getting the image width tag: + ## + ## @example + ## t = Tiff ("example.tif"); + ## width = t.getTag (256); + ## width = t.getTag (Tiff.TagID.ImageWidth); + ## width = t.getTag ("ImageWidth"); + ## @end example + ## + ## @seealso{setTag, getTagNames} + ## @end deftypefn + tag = __tiff_get_tag__ (t.tiff_handle, tag_name); endfunction function setTag (t, varargin) + + ## -*- texinfo -*- + ## @deftypefn {} Tiff.setTag (@var{tag_id}, @var{tag_value}) + ## @deftypefnx {} Tiff.setTag (@var{tag_name}, @var{tag_value}) + ## @deftypefnx {} Tiff.setTag (@var{tag_struct}) + ## + ## Set the value of tag identified by its ID number @var{tag_id} or + ## by its name @var{tag_name}, or set the value of a list of tags + ## arranged in a struct @var{tag_struct}. + ## + ## To get the ID of a tag use the @code{Tiff.TagID} structure. + ## + ## An example of setting the image width: + ## + ## @example + ## t = Tiff ("test.tif", "w"); + ## t.setTag (256, 100); + ## t.setTag (Tiff.TagID.ImageWidth, 100); + ## t.setTag ("ImageWidth", 100); + ## @end example + ## + ## An example of setting multiple tags: + ## + ## @example + ## t = Tiff ("test.tif", "w"); + ## tags = struct ("ImageWidth", 100, "ImageLength", 50); + ## t.setTag (tags); + ## @end example + ## + ## @seealso{getTag, getTagNames} + ## @end deftypefn + __tiff_set_tag__ (t.tiff_handle, varargin{:}); endfunction function argout = read (t) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{img} =} Tiff.read () + ## + ## Reads the image data of the current image directory. + ## + ## @seealso{getTag, setTag, write} + ## @end deftypefn + argout = __tiff_read__ (t.tiff_handle); endfunction function stripData = readEncodedStrip (t, stripNumber) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{strip} =} Tiff.readEncodedStrip (@var{stripNumber}) + ## + ## Read the data of the strip with index @var{stripNumber} from the + ## current image directory. @var{stripNumber} index is 1-based. + ## + ## Stips are numbered from top to bottom. Images with separate planes + ## will have all the strips of the first channel first then all the + ## strips of the second channel and so on. + ## + ## The strip data is returned in @var{strip}. The boundary strips in + ## image might have different dimensions than the rest of the strips + ## depending on the ImageLength and the RowsPerStrip tags. + ## + ## @seealso{read, readEncodedTile} + ## @end deftypefn + stripData = __tiff_read_encoded_strip__ (t.tiff_handle, stripNumber); endfunction function tileData = readEncodedTile (t, tileNumber) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{tile} =} Tiff.readEncodedTile (@var{tileNumber}) + ## + ## Read the data of the tile with index @var{tileNumber} from the + ## current image directory. @var{tileNumber} index is 1-based. + ## + ## Tiles are numbered from left to right and from top to bottom. Images + ## with separate planes will have all the tiles of the first channel + ## first then all the tiles of the second channel and so on. + ## + ## The tile data is returned in @var{tile}. The boundary tiles in + ## image might have different dimensions than the rest of the tiles + ## depending on tags: ImageLength, ImageWidth, TileLength and TileWidth. + ## + ## @seealso{read, readEncodedStrip} + ## @end deftypefn + tileData = __tiff_read_encoded_tile__ (t.tiff_handle, tileNumber); endfunction function [RGB, alpha] = readRGBAImage (t) + + ## -*- texinfo -*- + ## @deftypefn {} {[@var{rgb}, @var{alpha}] =} Tiff.readRGBAImage () + ## + ## Read the image data of the current image directory in RGBA mode. + ## The image 8-bit RGB data is returned in @var{rgb} and the transprency + ## data is returned in @var{alpha}. If the image has no transparency + ## data then the alpha array will be filled with the value 255. + ## + ## If the image data is any other format than 8-bit RGB then coversion + ## to 8-bit RGB is done internally. If you wish to read the actual image + ## data use the @code{read} method instead. + ## + ## This method uses the @qcode{"Orientation"} tag in the image to + ## correctly flip/rotate the image to match its orientation. + ## + ## @seealso{read, readRGBAStrip, readRGBATile} + ## @end deftypefn + [RGB, alpha] = __tiff_read_rgba_image__ (t.tiff_handle); endfunction function [RGB, alpha] = readRGBAStrip (t, row) + + ## -*- texinfo -*- + ## @deftypefn {} {[@var{rgb}, @var{alpha}] =} Tiff.readRGBAStrip (@var{row}) + ## + ## Read a strip of the image data that contains the given @var{row} in RGBA + ## mode. The strip 8-bit RGB data is returned in @var{rgb} and the + ## transprency data is returned in @var{alpha}. If the image has no + ## transparency data then the alpha array will be filled with the + ## value 255. + ## + ## Boundary strips may have different number of rows than the rest of + ## the strips in the image depending on the @qcode{"ImageLength"} and + ## @qcode{"RowsPerStrip"} tags. + ## + ## If the strip data is any other format than 8-bit RGB then coversion + ## to 8-bit RGB is done internally. If you wish to read the actual strip + ## data use the @code{readEncodedStrip} method instead. + ## + ## This method uses the @qcode{"Orientation"} tag in the image to + ## correctly flip/rotate the strip to match its orientation. + ## + ## @seealso{readEncodedStrip, readRGBAImage, readRGBATile} + ## @end deftypefn + [RGB, alpha] = __tiff_read_rgba_strip__ (t.tiff_handle, row); endfunction function [RGB, alpha] = readRGBATile (t, row, col) + + ## -*- texinfo -*- + ## @deftypefn {} {[@var{rgb}, @var{alpha}] =} Tiff.readRGBATile (@var{row}, @var{col}) + ## + ## Read a tile of the image data that contains the given @var{row} and + ## @var{col} in RGBA mode. The tile 8-bit RGB data is returned in @var{rgb} + ## and the transprency data is returned in @var{alpha}. If the image has + ## no transparency data then the alpha array will be filled with the + ## value 255. + ## + ## Boundary tiles may have different number dimensions than the rest of + ## the tiles in the image depending on @qcode{"ImageLength"}, + ## @qcode{"ImageWidth"}, @qcode{"TileLength"} and @qcode{"TileWidth"} tags. + ## + ## If the tile data is any other format than 8-bit RGB then coversion to + ## 8-bit RGB is done internally. If you wish to read the actual tile + ## data use the @code{readEncodedTile} method instead. + ## + ## This method uses the @qcode{"Orientation"} tag in the image to + ## correctly flip/rotate the tile to match its orientation. + ## + ## @seealso{readEncodedTile, readRGBAImage, readRGBAStrip} + ## @end deftypefn + [RGB, alpha] = __tiff_read_rgba_tile__ (t.tiff_handle, row, col); endfunction function write (t, imageData) + + ## -*- texinfo -*- + ## @deftypefn {} Tiff.write (@var{imageData}) + ## + ## Write the image pixel data @var{imageData} to the Tiff file. + ## + ## The class as well as the dimensions of the array @var{imageData} + ## must match the image tag values of @qcode{"ImageLength"}, + ## @qcode{"ImageWidth"}, @qcode{"SamplesPerPixel"}, @qcode{"BitsPerSample"} + ## and @qcode{"Photometric"} tags. + ## + ## For example, for a 10x10 8-bit RGB image, the @var{imageData} array + ## must be of class @qcode{"uint8"} and must have dimensions 10x10x3. + ## + ## @seealso{writeEncodedStrip, writeEncodedTile, read} + ## @end deftypefn + __tiff_write__ (t.tiff_handle, imageData); endfunction function writeEncodedStrip (t, stripNumber, imageData) + + ## -*- texinfo -*- + ## @deftypefn {} Tiff.writeEncodedStrip (@var{stripNumber}, @var{stripData}) + ## + ## Write the pixel data @var{stripData} to the strip of index + ## @var{stripnumber}. The strips are numbered from top to bottom. If the + ## image is configured for separate planes, then all the strips of the + ## first channel are numbered first then all the strips of the second + ## channel and so on. + ## + ## The class of the array @var{stripData} must match the value of the + ## @qcode{"BitsPerSample"} tag. + ## + ## If the array @var{stripData} has less elements than needed, it will + ## be silently padded with zeroes. If it has more elements than needed + ## the additional data will be truncated and a warning will be issued. + ## + ## @seealso{write, writeEncodedTile, read} + ## @end deftypefn + __tiff_write_encoded_strip__ (t.tiff_handle, stripNumber, imageData); endfunction function writeEncodedTile (t, tileNumber, imageData) + + ## -*- texinfo -*- + ## @deftypefn {} Tiff.writeEncodedTile (@var{tileNumber}, @var{tileData}) + ## + ## Write the pixel data @var{tileData} to the tile of index @var{tileNumber}. + ## The tiles are numbered from left to right and from top to bottom. If + ## the image is configured for separate planes, then all the tiles of + ## the first channel are numbered first then all the tiles of the second + ## channel and so on. + ## + ## The class of the array @var{tileData} must match the value of the + ## @qcode{"BitsPerSample"} tag. + ## + ## If the array @var{tileData} has less elements than needed, it will + ## be silently padded with zeroes. If it has more elements than needed + ## the additional data will be truncated and a warning will be issued. + ## + ## @seealso{writeEncodedStrip, write, read} + ## @end deftypefn + __tiff_write_encoded_tile__ (t.tiff_handle, tileNumber, imageData); endfunction function tf = isTiled (t) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{tf} =} Tiff.isTiled () + ## + ## Returns whether or not the image in the current directory is tiled. + ## + ## @seealso{numberOfTiles, numberOfStrips} + ## @end deftypefn + tf = __tiff_is_tiled__ (t.tiff_handle); endfunction function numStrips = numberOfStrips (t) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{numStrips} =} Tiff.numberOfStrips () + ## + ## Returns the number of strips in the image of the current directory. + ## + ## @seealso{numberOfTiles, isTiled} + ## @end deftypefn + numStrips = __tiff_number_of_strips__ (t.tiff_handle); endfunction function numTiles = numberOfTiles (t) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{numTiles} =} Tiff.numberOfTiles () + ## + ## Returns the number of tiles in the image of the current directory. + ## + ## @seealso{numberOfStrips, isTiled} + ## @end deftypefn + numTiles = __tiff_number_of_tiles__ (t.tiff_handle); endfunction function numDirs = numberOfDirectories (t) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{numDirs} =} Tiff.numberOfDirectories () + ## + ## Returns the number of directories in the image. + ## + ## @seealso{numberOfTiles, numberOfStrips} + ## @end deftypefn + numDirs = __tiff_number_of_directories__ (t.tiff_handle); endfunction function stripNumber = computeStrip (t, varargin) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{stripNumber} =} Tiff.computeStrip (@var{row}) + ## @deftypefnx {} {@var{stripNumber} =} Tiff.computeStrip (@var{row}, @var{plane}) + ## + ## Return the strip index @var{stripNumber} of the strip containing the + ## given @var{row}. If the image has separate planes, then an aditional + ## parameter @var{plane} is required to get the strip containing the @var{row} + ## in the specific plane. + ## + ## Stips are numbered from top to bottom. Images with separate planes + ## will have all the strips of the first channel first then all the + ## strips of the second channel and so on. + ## + ## @seealso{computeTile, numberOfStrips} + ## @end deftypefn + stripNumber = __tiff_compute_strip__ (t.tiff_handle, varargin{:}); endfunction function tileNumber = computeTile (t, varargin) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{tileNumber} =} Tiff.computeTile ([@var{row}, @var{col}]) + ## @deftypefnx {} {@var{tileNumber} =} Tiff.computeTile ([@var{row}, @var{col}], @var{plane}) + ## + ## Return the tile index @var{tileNumber} of the tile containing the + ## given @var{row} and @var{col}. If the image has separate planes, then + ## an aditional parameter @var{plane} is required to get the tile index + ## containing the @var{row} and @var{col} in the specific plane. + ## + ## Tiles are numbered from left to right and from top to bottom. Images + ## with separate planes will have all the tiles of the first channel + ## first then all the tiles of the second channel and so on. + ## + ## @seealso{computeStrip, numberOfTiles} + ## @end deftypefn + tileNumber = __tiff_compute_tile__ (t.tiff_handle, varargin{:}); endfunction function stripLength = getDefaultStripLength (t) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{stripLength} =} Tiff.getDefaultStripLength () + ## + ## Returns the number of rows @var{stripLength} of a reasonably sized + ## strip using the image dimensions and configuration tags. + ## + ## This value can be used to set the @qcode{"RowsPerStrip"} tag of a new + ## image but the @qcode{"ImageLength"}, @qcode{"ImageWidth"}, + ## @qcode{"SamplesPerPixel"}, @qcode{"BitsPerSample"}, and optionally + ## @qcode{"Compression"} tags must be set first for the number of rows + ## to be calculated from the correct image dimensions and configuration. + ## + ## @seealso{computeStrip, computeTile} + ## @end deftypefn + stripLength = __tiff_default_strip_length__ (t.tiff_handle); endfunction function tf = isBigEndian (t) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{tf} =} Tiff.isBigEndian () + ## + ## Returns whether the current image is of big-endian or little-endian + ## byte order. + ## + ## @seealso{isTiled} + ## @end deftypefn + tf = __tiff_is_big_endian__ (t.tiff_handle); endfunction function dirNum = currentDirectory (t) + + ## -*- texinfo -*- + ## @deftypefn {} {@var{dirNum} =} Tiff.currentDirectory () + ## + ## Get the 1-based index of the current directory in the file. + ## + ## @seealso{lastDirectory, nextDirectory} + ## @end deftypefn + dirNum = __tiff_current_directory__ (t.tiff_handle); endfunction function isLast = lastDirectory (t) + ## -*- texinfo -*- + ## @deftypefn {} {@var{isLast} =} Tiff.lastDirectory () + ## + ## Returns whether the current directory is the last directory in the + ## image file. + ## + ## @seealso{currentDirectory, nextDirectory} + ## @end deftypefn isLast = __tiff_last_directory__ (t.tiff_handle); endfunction function nextDirectory (t) + + ## -*- texinfo -*- + ## @deftypefn {} Tiff.nextDirectory () + ## + ## Switch to the next directory in the image file. + ## + ## @seealso{currentDirectory, lastDirectory} + ## @end deftypefn + __tiff_next_directory__ (t.tiff_handle); endfunction function setDirectory (t, dirNum) + + ## -*- texinfo -*- + ## @deftypefn {} Tiff.setDirectory (@var{dirNum}) + ## + ## Switches to the directory with index @var{dirNum}, where the indexing + ## is 1-based (starts counting at 1). + ## + ## @seealso{nextDirectory, currentDirectory} + ## @end deftypefn + __tiff_set_directory__ (t.tiff_handle, dirNum); endfunction function writeDirectory (t) + + ## -*- texinfo -*- + ## @deftypefn {} Tiff.writeDirectory () + ## + ## Write the data of the current directory to file and starts a new + ## directory for writing. + ## + ## Note that this is not needed for writing single-directory images + ## as it will be called internally when calling the @code{close} method. + ## + ## @seealso{setDirectory, rewriteDirectory} + ## @end deftypefn + __tiff_write_directory__ (t.tiff_handle); endfunction function rewriteDirectory (t) + + ## -*- texinfo -*- + ## @deftypefn {} Tiff.rewriteDirectory () + ## + ## Rewrite the modifications of the current directory to file and start + ## a new directory for writing. + ## + ## @seealso{writeDirectory, setDirectory} + ## @end deftypefn + __tiff_rewrite_directory__ (t.tiff_handle); endfunction function setSubDirectory (t, offset) + + ## -*- texinfo -*- + ## @deftypefn {} Tiff.setSubDirectory (@var{offset}) + ## + ## Sets the active directory to a sub-directory of the current directory + ## identified by its @var{offset}. + ## + ## Sub-directory offsets can be obtained from the @qcode{"SubIFD"} tag of + ## a directory. Switching to a sub-directory can only be done when the + ## parent directory is the current directory. + ## + ## @seealso{setDirectory, currentDirecory} + ## @end deftypefn + __tiff_set_sub_directory__ (t.tiff_handle, offset); endfunction function offset = getDirectoryOffset (t) + + ## -*- texinfo -*- + ## @deftypefn {} Tiff.getDirectoryOffset () + ## + ## Gets the offset in bytes of the current directory relative to the + ## start of the Tiff file. + ## + ## @seealso{setSubDirectory, setDirectory} + ## @end deftypefn + offset = __tiff_get_directory_offset__ (t.tiff_handle); endfunction - - % TODO(maged): add documentation and make print_usage work endmethods methods (Static = true) function versionString = getVersion() + + ## -*- texinfo -*- + ## @deftypefn {} {@var{versionString} =} Tiff.getVersion () + ## + ## Get a string with the version information of the LibTIFF library + ## used internally by this interface. + ## + ## @end deftypefn + versionString = __tiff_version__ (); endfunction function tagNames = getTagNames () + + ## -*- texinfo -*- + ## @deftypefn {} {@var{tagNames} =} Tiff.getTagNames () + ## + ## Get a cell array of all the tag names supported. + ## + ## @seealso{Tiff.TagID, getTag, setTag} + ## @end deftypefn + tagNames = fieldnames (Tiff.TagID); endfunction function setLibTIFFErrorsEnabled(state) + + ## -*- texinfo -*- + ## @deftypefn {} Tiff.setLibTIFFErrorsEnabled (@var{state}) + ## + ## Enable or disable relaying the internal errors and warnings + ## issued by LibTIFF (enabled by default). + ## + ## @end deftypefn + __tiff_set_errors_enabled__ (state); endfunction endmethods