class_docstr: A ImageIO Plugin.
  
  This is an abstract plugin that documents the v3 plugin API interface. A
  plugin is an adapter/wrapper around a backend that converts a request from
  iio.core (e.g., read an image from file) into a sequence of instructions for
  the backend that fulfill the request.
  
  Plugin authors may choose to subclass this class when implementing a new
  plugin, but aren't obliged to do so. As long as the plugin class implements
  the interface (methods) described below the ImageIO core will treat it just
  like any other plugin.
  
  
  Parameters
  ----------
  request : iio.Request
      A request object that represents the users intent. It provides a
      standard interface to access the various ImageResources and serves them
      to the plugin as a file object (or file). Check the docs for details.
  **kwargs : Any
      Additional configuration arguments for the plugin or backend. Usually
      these match the configuration arguments available on the backend and
      are forwarded to it.
  
  
  Raises
  ------
  InitializationError
      During ``__init__`` the plugin tests if it can fulfill the request. If
      it can't, e.g., because the request points to a file in the wrong
      format, then it should raise an ``InitializationError`` and provide a
      reason for failure. This reason may be reported to the user.
  ImportError
      Plugins will be imported dynamically when listed in
      ``iio.config.known_plugins`` to fulfill requests. This way, users only
      have to load plugins/backends they actually use. If this plugin's backend
      is not installed, it should raise an ``ImportError`` either during
      module import or during class construction.
  
  Notes
  -----
  Upon successful construction the plugin takes ownership of the provided
  request. This means that it is the plugin's responsibility to call
  request.finish() to close the resource when it is no longer needed.
  
  Plugins _must_ implement a context manager that closes and cleans any
  resources held by the plugin upon exit.
class_docstr_tok: ["A","ImageIO","Plugin",".","This","is","an","abstract","plugin","that","documents","the","v3","plugin","API","interface",".","A","plugin","is","an","adapter\/wrapper","around","a","backend","that","converts","a","request","from","iio.core","(","e.g.",",","read","an","image","from","file",")","into","a","sequence","of","instructions","for","the","backend","that","fulfill","the","request",".","Plugin","authors","may","choose","to","subclass","this","class","when","implementing","a","new","plugin",",","but","are","n't","obliged","to","do","so",".","As","long","as","the","plugin","class","implements","the","interface","(","methods",")","described","below","the","ImageIO","core","will","treat","it","just","like","any","other","plugin",".","Parameters","--","--","--","--","--","request",":","iio.Request","A","request","object","that","represents","the","users","intent",".","It","provides","a","standard","interface","to","access","the","various","ImageResources","and","serves","them","to","the","plugin","as","a","file","object","(","or","file",")",".","Check","the","docs","for","details",".","*","*","kwargs",":","Any","Additional","configuration","arguments","for","the","plugin","or","backend",".","Usually","these","match","the","configuration","arguments","available","on","the","backend","and","are","forwarded","to","it",".","Raises","--","--","--","InitializationError","During","``","__init__","``","the","plugin","tests","if","it","can","fulfill","the","request",".","If","it","ca","n't",",","e.g.",",","because","the","request","points","to","a","file","in","the","wrong","format",",","then","it","should","raise","an","``","InitializationError","``","and","provide","a","reason","for","failure",".","This","reason","may","be","reported","to","the","user",".","ImportError","Plugins","will","be","imported","dynamically","when","listed","in","``","iio.config.known_plugins","``","to","fulfill","requests",".","This","way",",","users","only","have","to","load","plugins\/backends","they","actually","use",".","If","this","plugin","'s","backend","is","not","installed",",","it","should","raise","an","``","ImportError","``","either","during","module","import","or","during","class","construction",".","Notes","--","--","-","Upon","successful","construction","the","plugin","takes","ownership","of","the","provided","request",".","This","means","that","it","is","the","plugin","'s","responsibility","to","call","request.finish","(",")","to","close","the","resource","when","it","is","no","longer","needed",".","Plugins","_must_","implement","a","context","manager","that","closes","and","cleans","any","resources","held","by","the","plugin","upon","exit","."]
docstr: Read a ndimage.
  
  The ``read`` method loads a (single) ndimage, located at ``index`` from
  the requested ImageResource.
  
  It is at the plugin's descretion to decide (and document) what
  constitutes a single ndimage. A sensible way to make this decision is to
  choose based on the ImageResource's format and on what users will expect
  from such a format. For example, a sensible choice for a TIFF file
  produced by an ImageJ hyperstack is to read it as a volumetric ndimage
  (1 color dimension followed by 3 spatial dimensions). On the other hand,
  a sensible choice for a MP4 file produced by Davinci Resolve is to treat
  each frame as a ndimage (2 spatial dimensions followed by 1 color
  dimension).
  
  The value ``index=None`` is special. It requests the plugin to load all
  ndimages in the file and stack them along a new first axis. For example,
  if a MP4 file is read with ``index=None`` and the plugin identifies
  single frames as ndimages, then the plugin should read all frames and
  stack them into a new ndimage which now contains a time axis as its
  first axis. If a PNG file (single image format) is read with
  ``index=None`` the plugin does a very similar thing: It loads all
  ndimages in the file (here it's just one) and stacks them along a new
  first axis, effectively prepending an axis with size 1 to the image. If
  a plugin does not wish to support ``index=None`` it should set a more
  sensible default and raise a ``ValueError`` when requested to read using
  ``index=None``.
  
  Parameters
  ----------
  index : int
      If the ImageResource contains multiple ndimages, and index is an
      integer, select the index-th ndimage from among them and return it.
      If index is an ellipsis (...), read all ndimages in the file and
      stack them along a new batch dimension. If index is None, let the
      plugin decide. If the index is out of bounds a ``ValueError`` is
      raised.
  **kwargs : Any
      The read method may accept any number of plugin-specific keyword
      arguments to further customize the read behavior. Usually these
      match the arguments available on the backend and are forwarded to
      it.
  
  Returns
  -------
  ndimage : np.ndarray
      A ndimage containing decoded pixel data (sometimes called bitmap).
  
  Notes
  -----
  The ImageResource from which the plugin should read is managed by the
  provided request object. Directly accessing the managed ImageResource is
  _not_ permitted. Instead, you can get FileLike access to the
  ImageResource via request.get_file().
  
  If the backend doesn't support reading from FileLike objects, you can
  request a temporary file to pass to the backend via
  ``request.get_local_filename()``. This is, however, not very performant
  (involves copying the Request's content into a temporary file), so you
  should avoid doing this whenever possible. Consider it a fallback method
  in case all else fails.
docstr_tok: ["Read","a","ndimage",".","The","``","read","``","method","loads","a","(","single",")","ndimage",",","located","at","``","index","``","from","the","requested","ImageResource",".","It","is","at","the","plugin","'s","descretion","to","decide","(","and","document",")","what","constitutes","a","single","ndimage",".","A","sensible","way","to","make","this","decision","is","to","choose","based","on","the","ImageResource","'s","format","and","on","what","users","will","expect","from","such","a","format",".","For","example",",","a","sensible","choice","for","a","TIFF","file","produced","by","an","ImageJ","hyperstack","is","to","read","it","as","a","volumetric","ndimage","(","1","color","dimension","followed","by","3","spatial","dimensions",")",".","On","the","other","hand",",","a","sensible","choice","for","a","MP4","file","produced","by","Davinci","Resolve","is","to","treat","each","frame","as","a","ndimage","(","2","spatial","dimensions","followed","by","1","color","dimension",")",".","The","value","``","index=None","``","is","special",".","It","requests","the","plugin","to","load","all","ndimages","in","the","file","and","stack","them","along","a","new","first","axis",".","For","example",",","if","a","MP4","file","is","read","with","``","index=None","``","and","the","plugin","identifies","single","frames","as","ndimages",",","then","the","plugin","should","read","all","frames","and","stack","them","into","a","new","ndimage","which","now","contains","a","time","axis","as","its","first","axis",".","If","a","PNG","file","(","single","image","format",")","is","read","with","``","index=None","``","the","plugin","does","a","very","similar","thing",":","It","loads","all","ndimages","in","the","file","(","here","it","'s","just","one",")","and","stacks","them","along","a","new","first","axis",",","effectively","prepending","an","axis","with","size","1","to","the","image",".","If","a","plugin","does","not","wish","to","support","``","index=None","``","it","should","set","a","more","sensible","default","and","raise","a","``","ValueError","``","when","requested","to","read","using","``","index=None","``",".","Parameters","--","--","--","--","--","index",":","int","If","the","ImageResource","contains","multiple","ndimages",",","and","index","is","an","integer",",","select","the","index-th","ndimage","from","among","them","and","return","it",".","If","index","is","an","ellipsis","(","...",")",",","read","all","ndimages","in","the","file","and","stack","them","along","a","new","batch","dimension",".","If","index","is","None",",","let","the","plugin","decide",".","If","the","index","is","out","of","bounds","a","``","ValueError","``","is","raised",".","*","*","kwargs",":","Any","The","read","method","may","accept","any","number","of","plugin-specific","keyword","arguments","to","further","customize","the","read","behavior",".","Usually","these","match","the","arguments","available","on","the","backend","and","are","forwarded","to","it",".","Returns","--","--","--","-","ndimage",":","np.ndarray","A","ndimage","containing","decoded","pixel","data","(","sometimes","called","bitmap",")",".","Notes","--","--","-","The","ImageResource","from","which","the","plugin","should","read","is","managed","by","the","provided","request","object",".","Directly","accessing","the","managed","ImageResource","is","_not_","permitted",".","Instead",",","you","can","get","FileLike","access","to","the","ImageResource","via","request.get_file","(",")",".","If","the","backend","does","n't","support","reading","from","FileLike","objects",",","you","can","request","a","temporary","file","to","pass","to","the","backend","via","``","request.get_local_filename","(",")","``",".","This","is",",","however",",","not","very","performant","(","involves","copying","the","Request","'s","content","into","a","temporary","file",")",",","so","you","should","avoid","doing","this","whenever","possible",".","Consider","it","a","fallback","method","in","case","all","else","fails","."]
code: def read(self, *, index: int = 0) -> np.ndarray:
      """Read a ndimage.
  
      The ``read`` method loads a (single) ndimage, located at ``index`` from
      the requested ImageResource.
  
      It is at the plugin's descretion to decide (and document) what
      constitutes a single ndimage. A sensible way to make this decision is to
      choose based on the ImageResource's format and on what users will expect
      from such a format. For example, a sensible choice for a TIFF file
      produced by an ImageJ hyperstack is to read it as a volumetric ndimage
      (1 color dimension followed by 3 spatial dimensions). On the other hand,
      a sensible choice for a MP4 file produced by Davinci Resolve is to treat
      each frame as a ndimage (2 spatial dimensions followed by 1 color
      dimension).
  
      The value ``index=None`` is special. It requests the plugin to load all
      ndimages in the file and stack them along a new first axis. For example,
      if a MP4 file is read with ``index=None`` and the plugin identifies
      single frames as ndimages, then the plugin should read all frames and
      stack them into a new ndimage which now contains a time axis as its
      first axis. If a PNG file (single image format) is read with
      ``index=None`` the plugin does a very similar thing: It loads all
      ndimages in the file (here it's just one) and stacks them along a new
      first axis, effectively prepending an axis with size 1 to the image. If
      a plugin does not wish to support ``index=None`` it should set a more
      sensible default and raise a ``ValueError`` when requested to read using
      ``index=None``.
  
      Parameters
      ----------
      index : int
          If the ImageResource contains multiple ndimages, and index is an
          integer, select the index-th ndimage from among them and return it.
          If index is an ellipsis (...), read all ndimages in the file and
          stack them along a new batch dimension. If index is None, let the
          plugin decide. If the index is out of bounds a ``ValueError`` is
          raised.
      **kwargs : Any
          The read method may accept any number of plugin-specific keyword
          arguments to further customize the read behavior. Usually these
          match the arguments available on the backend and are forwarded to
          it.
  
      Returns
      -------
      ndimage : np.ndarray
          A ndimage containing decoded pixel data (sometimes called bitmap).
  
      Notes
      -----
      The ImageResource from which the plugin should read is managed by the
      provided request object. Directly accessing the managed ImageResource is
      _not_ permitted. Instead, you can get FileLike access to the
      ImageResource via request.get_file().
  
      If the backend doesn't support reading from FileLike objects, you can
      request a temporary file to pass to the backend via
      ``request.get_local_filename()``. This is, however, not very performant
      (involves copying the Request's content into a temporary file), so you
      should avoid doing this whenever possible. Consider it a fallback method
      in case all else fails.
  
      """
      raise NotImplementedError()
  
file_path: imageio/imageio/core/v3_plugin_api.py
imports: from .None import Request
  from ..typing import ArrayLike
  import numpy
  from typing import Optional, Dict, Any, Tuple, Union, List, Iterator
  from dataclasses import dataclass
label_desc: Use image node_id 2 for calling the PluginV3 obj's underlying member method code with example usage: obj.read() without return types