Create Adapter to Read Unsupported Image Formats for Blocked Processing

Classdef

The LanAdapter class begins with the keyword classdef. The classdef defines the class name and indicates that LanAdapter inherits from the images.blocked.Adapter superclass. The images.blocked.Adapter class is an abstract class that defines the signature for methods that blockedImage uses to read image files on disk.

classdef LanAdapter < images.blocked.Adapter

Properties

Following the classdef section, the LanAdapter class contains a block of class properties that stores metadata from the file header. Other classes that also inherit from images.blocked.Adapter, but that support different file formats, can have different properties.

   properties
      Filename
      NumBands
      SelectedBands
      ImageSize
  end

Required Methods

Following the properties block, define a methods block. Adapter classes have three required methods that all adapter classes must implement: openToRead, getInfo, and getIOBlock. Each method is implemented differently for different file formats, depending on what tools are available for reading the specific files.

Then, implement the first method, openToRead, which opens the source for reading. The openToRead function must have two input arguments, obj and source. The obj argument refers to the concrete instance of the adapter. The source argument is the name of the LAN file.

For this adapter class, the openToRead function also parses the LAN file header and sets properties of the adapter. The sample LanAdapter class only supports uint8 data type files, so the function validates the pack type of the LAN file.

    methods
        
        function openToRead(obj,source)  

            % Open the file
            obj.Filename = source;
            fid = fopen(source,"r");

            % Verify that the file begins with the headword "HEADER" or
            % "HEAD74", as per the Erdas LAN file specification            
            headword = fread(fid,6,"uint8=>char");
            headword = headword'
            if ~(strcmp(headword,"HEADER") || strcmp(headword,"HEAD74"))
                error("Invalid LAN file header.");
            end

            % Read the data type from the header
            pack_type = fread(fid,1,"uint16",0,"ieee-le")
            if ~isequal(pack_type,0) 
                error("Only uint8 data supported.");
            end
              
            % Provide band information
            numBands = fread(fid,1,"uint16",0,"ieee-le")
            obj.NumBands = numBands;
            if isempty(obj.SelectedBands)        
                obj.SelectedBands = 1:numBands;  % only set default
            end

            % Specify image size
            unused_field = fread(fid,6,"uint8",0,"ieee-le");
            width = fread(fid,1,"uint32",0,"ieee-le")
            height = fread(fid,1,"uint32",0,"ieee-le")
            obj.ImageSize = [height width];
        end

Implement the second required method, getInfo, which returns a structure containing information about the data. The structure has four required fields.

      function info = getInfo(obj)
          numSelectedBands = numel(obj.SelectedBands);
          info.Size = [obj.ImageSize numSelectedBands];
          info.Datatype = "uint8";
          info.IOBlockSize = [100 100 numSelectedBands];
          info.InitialValue = uint8(0);
      end

Implement the third required method, getIOBlock, which reads one block of data specified by the block subscript ioBlockSub. The function signature for the getIOBlock function has three input arguments. This adapter assumes the LAN image has one resolution level. You can ignore the third input argument corresponding to the resolution level by specifying the value as ~.

The getIOBlock function calculates the pixel indices corresponding to the block subscript ioBlockSub, then reads that block of data by using the multibandread function. The call to multibandread is similar to that for an in-memory image, with the addition of specified row and column indices for the block.

        function data = getIOBlock(obj,ioBlockSub,~)
            info = getInfo(obj);
            blockSize = info.IOBlockSize;
            regionStart = (ioBlockSub-1).*blockSize + 1;
            regionEnd = min(ioBlockSub.*blockSize,info.Size);

            rows = regionStart(1):regionEnd(1);
            cols = regionStart(2):regionEnd(2);

            fullSize = [obj.ImageSize obj.NumBands];
            data = multibandread(obj.Filename,fullSize, ...
                  "uint8=>uint8",128,"bil","ieee-le", ...
                  {"Row","Direct",rows}, ...
                  {"Column","Direct",cols}, ...
                  {"Band","Direct",obj.SelectedBands});
          end

Optional Methods

When you write a custom adapter, you can optionally implement additional methods to perform actions such as writing data and performing clean up tasks. For a full list of optional methods, see images.blocked.Adapter.

Although these methods are not required by the images.blocked.Adapter abstract class, your file format might require you to implement one or more of these methods in the class definition. For example, you might need to implement the close method to close file handles and perform other class clean-up responsibilities.

The LanAdapter class in this topic is read-only and does not need to implement optional methods. If you want to write output to a LAN format file, or another file with a format that blockedImage does not support, then implement the openToWrite and setIOBlock methods. The LanAdapter class does not need to implement the close method because the multibandread function does not need maintenance of open file handles.

End Methods Block and Classdef Block

After you define the required methods and any optional methods, end the methods block and the classdef block.

   end % methods
end % LanAdapter

Now that you understand how the LanAdapter class works, you can use it in block processing workflows. The following topic shows how to use the LanAdapter class to read RGB data from a multispectral LAN file and write the RGB data to the JPG file format.