Module ij
Package ij.plugin

# Class AVI_Reader

java.lang.Object
ij.ImageStack
ij.VirtualStack
ij.plugin.AVI_Reader

All Implemented Interfaces:
  `PlugIn`

public class AVI_Reader extends VirtualStack implements PlugIn

     ImageJ Plugin for reading an AVI file into an image stack
            (one slice per video frame)

     Restrictions and Notes:
                    - Only few formats supported:
                            - uncompressed 8 bit with palette (=LUT)
                            - uncompressed 8 invalid input: '&' 16 bit grayscale
                            - uncompressed 24 invalid input: '&' 32 bit RGB (alpha channel ignored)
                            - uncompressed 32 bit AYUV (alpha channel ignored)
                            - various YUV 4:2:2 and 4:2:0 compressed formats (i.e., formats with
                                                      full luminance resolution, but reduced chroma resolution
                            - png or jpeg-encoded individual frames.
                              Note that most MJPG (motion-JPEG) formats are not read correctly.
                    - Does not read avi formats with more than one frame per chunk
                    - Palette changes during the video not supported
                    - Out-of-sequence frames (sequence given by index) not supported
                    - Different frame sizes in one file (rcFrame) not supported
                    - Conversion of (A)YUV formats to grayscale is non-standard:
                      All 255 levels are kept as in the input (i.e. the full dynamic
                      range of data from a frame grabber is preserved).
                      For standard behavior, use "Brightnessinvalid input: '&Contrast'", Press "Set",
                      enter "Min." 16, "Max." 235, and press "Apply".
                    - Restrictions for AVIs with blank frames:
                      Currently only supported with AVI-2 type index.
                      Blank frames are ignored.
                      Selection of start and end frames is inconsistent between normal and
                      virtual stacks.
                      Timing in slice info is incorrect unless read as virtual stack.
                    - Note: As a last frame, one can enter '0' (= last frame),
                      '-1' (last frame -1), etc.

     Version History:
             2008-04-29
                      based on a plugin by Daniel Marsh and Wayne Rasband;
                      modifications by Michael Schmid
                    - Support for several other formats added, especially some YUV
                      (also named YCbCr) formats
                    - Uneven chunk sizes fixed
                    - Negative biHeight fixed
                    - Audio or second video stream don't cause a problem
                    - Can read part of a file (specify start invalid input: '&' end frame numbers)
                    - Can convert YUV and RGB to grayscale (does not convert 8-bit with palette)
                    - Can flip vertically
                    - Can create a virtual stack
                    - Added slice label: time of the frame in the movie
                    - Added a public method 'getStack' that does not create an image window
                    - More compact code, especially for reading the header (rewritten)
                    - In the code, bitmapinfo items have their canonical names.
             2008-06-08
                    - Support for png and jpeg/mjpg encoded files added
                    - Retrieves animation speed from image frame rate
                    - Exception handling without multiple error messages
             2008-07-03
                    - Support for 16bit AVIs coded by MIL (Matrox Imaging Library)
             2009-03-06
                    - Jesper Soendergaard Pedersen added support for extended (large) AVI files,
                      also known as 'AVI 2.0' or 'OpenDML 1.02 AVI file format extension'
                      For Virtual stacks, it reads the 'AVI 2.0' index (indx and ix00 tags).
                      This results in a dramatic speed increase in loading of virtual stacks.
                      If indx and ix00 are not found or bIndexType is unsupported, as well as for
                      non-virtual stacks it finds the frames 'the old way', by scanning the whole file.
                    - Fixes a bug where it read too many frames.
                      This version was published as external plugin.
             2011-12-03
                    - Minor updates invalid input: '&' cleanup for integration into ImageJ again.
                    - Multithread-compliant.
             2011-12-10
                    - Based on a plugin by Jesper Soendergaard Pedersen, also reads the 'idx1' index of
                      AVI 1 files, speeding up initial reading of virtual stacks also for smaller files.
                    - When the first frame to read is > 1, uses the index to quickly skip the initial frames.
                    - Creates a unique window name.
                    - Opens MJPG files also if they do not contain Huffman tables
             2012-02-01
                    - added support for YV12, I420, NV12, NV21 (planar formats with 2x2 U and V subsampling)
             2012-12-04
                    - can read AVI-2 files with blank frames into a virtual stack
             2013-10-29
                    - can read MJPG files where the frames don't have the same pixel number as the overall video
             2015-09-28
                    - reads most ImageJ AVI1 files with size>4 GB (incorrectly written by ImageJ versions before 1.50b)
             2017-04-21
                    - bugfix: file was not closed in case of dialog cancelled or some IO errors.
          - Tries to recover data from truncated files.

     The AVI format looks like this:
     RIFF AVI                                       RIFF HEADER, AVI CHUNK
             | LIST hdrl                    MAIN AVI HEADER
             | | avih                               AVI HEADER
             | | LIST strl                  STREAM LIST(s) (One per stream)
             | | | strh                             STREAM HEADER (Required after above; fourcc type is 'vids' for video stream)
             | | | strf                             STREAM FORMAT (for video: BitMapInfo; may also contain palette)
             | | | strd                             OPTIONAL -- STREAM DATA (ignored in this plugin)
             | | | strn                             OPTIONAL -- STREAM NAME (ignored in this plugin)
             | | | indx                             OPTIONAL -- MAIN 'AVI 2.0' INDEX
             | LIST movi                    MOVIE DATA
             | | ix00                               partial video index of 'AVI 2.0', usually missing in AVI 1 (ix01 would be for audio)
             | | [rec]                              RECORD DATA (one record per frame for interleaved video; optional, unsupported in this plugin)
             | | |-dataSubchunks    RAW DATA: '??wb' for audio, '??db' and '??dc' for uncompressed and
             | |                                    compressed video, respectively. "??" denotes stream number, usually "00" or "01"
             | idx1                                 AVI 1 INDEX ('old-style'); may be missing in very old formats
     RIFF AVIX                              'AVI 2.0' only: further chunks
             | LIST movi                    more movie data, as above, usually with ix00 index
                                                            Any number of further chunks (RIFF tags) may follow

     Items ('chunks') with one fourcc (four-character code such as 'strh') start with two 4-byte words:
     the fourcc and the size of the data area.
     Items with two fourcc (e.g. 'LIST hdrl') have three 4-byte words: the first fourcc, the size and the
     second fourcc. Note that the size includes the 4 bytes needed for the second fourcc.

     Chunks with fourcc 'JUNK' can appear anywhere and should be ignored.

## Field Summary

### Fields inherited from class ij.ImageStack

`cTable`

## Constructor Summary

Constructors
Constructor
Description
`AVI_Reader()`

## Method Summary

Modifier and Type
Method
Description
`void`
`deleteSlice(int n)`
Deletes the specified image from this virtual stack (if it is one), where 1<=n<=nslices.
`void`
`displayDialog(boolean displayDialog)`
`String`
`getErrorText()`
Returns a description of the error reading the file with `makeStack` or null if no error
`int`
`getHeight()`
Returns the image height of the virtual stack
`ImagePlus`
`getImagePlus()`
Returns the ImagePlus opened by run().
`ImageProcessor`
`getProcessor(int n)`
Returns an ImageProcessor for the specified slice of this virtual stack (if it is one) where 1<=n<=nslices.
`int`
`getSize()`
Returns the number of images in this virtual stack (if it is one)
`String`
`getSliceLabel(int n)`
Returns the label of the specified slice in this virtual stack (if it is one).
`int`
`getWidth()`
Returns the image width of the virtual stack
`ImageStack`
`makeStack(String path, int firstFrame, int lastFrame, boolean isVirtual, boolean convertToGray, boolean flipVertical)`
Create an ImageStack from an avi file with given path.
`static ImagePlus`
`open(String path, boolean virtual)`
Opens an AVI file as a stack in memory or a virtual stack.
`static ImagePlus`
`open(String path, String options)`
Opens an AVI file, where 'options' can contain 'virtual' (open as virtual stack), 'convert' (convert color images to grayscale) or 'flip' (flip vertically).
`static ImagePlus`
`openVirtual(String path)`
Opens an AVI file as a virtual stack.
`void`
`run(String arg)`
The plugin is invoked by ImageJ using this method.
`void`
`setVirtual(boolean virtual)`
Open as virtual stack?

### Methods inherited from class ij.VirtualStack

`addSlice, addSlice, addSlice, addSlice, deleteLastSlice, getBitDepth, getDirectory, getFileName, getImageArray, getPixels, getProperties, isVirtual, reduce, saveChanges, setBitDepth, setIndexes, setPixels, setSliceLabel, size, sortDicom, translate, trim`

### Methods inherited from class ij.ImageStack

`addSlice, addUnsignedShortSlice, convertToFloat, create, create, crop, drawSphere, duplicate, getColorModel, getRoi, getShortSliceLabel, getShortSliceLabel, getSliceLabels, getVoxel, getVoxels, getVoxels, isHSB, isHSB32, isLab, isRGB, setColorModel, setOptions, setProcessor, setRoi, setVoxel, setVoxels, setVoxels, toString, update`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Constructor Details

### AVI_Reader

public AVI_Reader()

## Method Details

### run

public void run(String arg)
The plugin is invoked by ImageJ using this method.

Specified by:
  `run` in interface `PlugIn`
Parameters:
  `arg` - String 'arg' may be used to select the path. If it is an empty string, a file open dialog is shown, and the resulting ImagePlus is displayed thereafter. The ImagePlus is not displayed if 'arg' is a non-empty String; it can be retrieved with getImagePlus().

### getImagePlus

public ImagePlus getImagePlus()
Returns the ImagePlus opened by run().

### openVirtual

public static ImagePlus openVirtual(String path)
Opens an AVI file as a virtual stack. The ImagePlus is not displayed.

### open

public static ImagePlus open(String path, String options)
Opens an AVI file, where 'options' can contain 'virtual' (open as virtual stack), 'convert' (convert color images to grayscale) or 'flip' (flip vertically). The ImagePlus is not displayed.

### open

public static ImagePlus open(String path, boolean virtual)
Opens an AVI file as a stack in memory or a virtual stack. The ImagePlus is not displayed.

### makeStack

public ImageStack makeStack(String path, int firstFrame, int lastFrame, boolean isVirtual, boolean convertToGray, boolean flipVertical)
Create an ImageStack from an avi file with given path.

Parameters:
  `path` - Directoy+filename of the avi file
  `firstFrame` - Number of first frame to read (first frame of the file is 1)
  `lastFrame` - Number of last frame to read or 0 for reading all, -1 for all but last...
  `isVirtual` - Whether to return a virtual stack
  `convertToGray` - Whether to convert color images to grayscale
Returns:
  Returns the stack (may be incomplete on error); null on failure. The stack returned may be non-null, but have a length of zero if no suitable frames were found. Use `getErrorText` to determine whether there has been an error reading the file. For virtual stacks, not that I/O errors may also occur later, when reading the frames.

### getErrorText

public String getErrorText()
Returns a description of the error reading the file with `makeStack` or null if no error

### getProcessor

public ImageProcessor getProcessor(int n)
Returns an ImageProcessor for the specified slice of this virtual stack (if it is one) where 1<=n<=nslices. Returns null if no virtual stack or no slices or error reading the frame.

Overrides:
  `getProcessor` in class `VirtualStack`

### getWidth

public int getWidth()
Returns the image width of the virtual stack

Overrides:
  `getWidth` in class `ImageStack`

### getHeight

public int getHeight()
Returns the image height of the virtual stack

Overrides:
  `getHeight` in class `ImageStack`

### getSize

public int getSize()
Returns the number of images in this virtual stack (if it is one)

Overrides:
  `getSize` in class `VirtualStack`

### getSliceLabel

public String getSliceLabel(int n)
Returns the label of the specified slice in this virtual stack (if it is one).

Overrides:
  `getSliceLabel` in class `VirtualStack`

### deleteSlice

public void deleteSlice(int n)
Deletes the specified image from this virtual stack (if it is one), where 1<=n<=nslices.

Overrides:
  `deleteSlice` in class `VirtualStack`

### displayDialog

public void displayDialog(boolean displayDialog)

### setVirtual

public void setVirtual(boolean virtual)
Open as virtual stack?