--- 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