:py:mod:`kwcoco.util.lazy_frame_backends`
=========================================

.. py:module:: kwcoco.util.lazy_frame_backends

.. autoapi-nested-parse::

   Ducktyped interfaces for loading subregions of images with standard slice
   syntax



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   kwcoco.util.lazy_frame_backends.LazySpectralFrameFile
   kwcoco.util.lazy_frame_backends.LazyRasterIOFrameFile
   kwcoco.util.lazy_frame_backends.LazyGDalFrameFile



Functions
~~~~~~~~~

.. autoapisummary::

   kwcoco.util.lazy_frame_backends._have_gdal
   kwcoco.util.lazy_frame_backends._have_rasterio
   kwcoco.util.lazy_frame_backends._have_spectral
   kwcoco.util.lazy_frame_backends._demo_geoimg_with_nodata
   kwcoco.util.lazy_frame_backends._rectify_slice_dim
   kwcoco.util.lazy_frame_backends._validate_nonzero_data
   kwcoco.util.lazy_frame_backends._read_envi_header



Attributes
~~~~~~~~~~

.. autoapisummary::

   kwcoco.util.lazy_frame_backends.profile
   kwcoco.util.lazy_frame_backends._GDAL_DTYPE_LUT


.. py:data:: profile
   

   

.. py:function:: _have_gdal()


.. py:function:: _have_rasterio()


.. py:function:: _have_spectral()


.. py:data:: _GDAL_DTYPE_LUT
   

   

.. py:class:: LazySpectralFrameFile(fpath)

   Bases: :py:obj:`ubelt.NiceRepr`

   Potentially faster than GDAL for HDR formats.

   .. py:method:: _ds(self)


   .. py:method:: available(self)
      :classmethod:

      Returns True if this backend is available


   .. py:method:: ndim(self)
      :property:


   .. py:method:: shape(self)
      :property:


   .. py:method:: dtype(self)
      :property:


   .. py:method:: __nice__(self)


   .. py:method:: __getitem__(self, index)



.. py:class:: LazyRasterIOFrameFile(fpath)

   Bases: :py:obj:`ubelt.NiceRepr`

   fpath = '/home/joncrall/.cache/kwcoco/demo/large_hyperspectral/big_img_128.bsq'
   lazy_rio = LazyRasterIOFrameFile(fpath)
   ds = lazy_rio._ds

   .. py:method:: available(self)
      :classmethod:

      Returns True if this backend is available


   .. py:method:: _ds(self)


   .. py:method:: ndim(self)
      :property:


   .. py:method:: shape(self)
      :property:


   .. py:method:: dtype(self)
      :property:


   .. py:method:: __nice__(self)


   .. py:method:: __getitem__(self, index)



.. py:function:: _demo_geoimg_with_nodata()

   .. rubric:: Example

   from kwcoco.util.lazy_frame_backends import *  # NOQA
   fpath = _demo_geoimg_with_nodata()
   self = LazyGDalFrameFile.demo()


.. py:class:: LazyGDalFrameFile(fpath, nodata=None)

   Bases: :py:obj:`ubelt.NiceRepr`

   .. todo::

      - [ ] Move to its own backend module
      - [ ] When used with COCO, allow the image metadata to populate the
            height, width, and channels if possible.

   .. rubric:: Example

   >>> # xdoctest: +REQUIRES(module:osgeo)
   >>> self = LazyGDalFrameFile.demo()
   >>> print('self = {!r}'.format(self))
   >>> self[0:3, 0:3]
   >>> self[:, :, 0]
   >>> self[0]
   >>> self[0, 3]

   >>> # import kwplot
   >>> # kwplot.imshow(self[:])

   :Parameters: * **nodata**
                * **masking_method**

   .. rubric:: Example

   >>> # See if we can reproduce the INTERLEAVE bug

   data = np.random.rand(128, 128, 64)
   import kwimage
   import ubelt as ub
   from os.path import join
   dpath = ub.ensure_app_cache_dir('kwcoco/tests/reader')
   fpath = join(dpath, 'foo.tiff')
   kwimage.imwrite(fpath, data, backend='skimage')
   recon1 = kwimage.imread(fpath)
   recon1.shape

   self = LazyGDalFrameFile(fpath)
   self.shape
   self[:]

   .. py:method:: available(self)
      :classmethod:

      Returns True if this backend is available


   .. py:method:: _ds(self)


   .. py:method:: demo(cls, key='astro', dsize=None)
      :classmethod:


   .. py:method:: ndim(self)
      :property:


   .. py:method:: shape(self)
      :property:


   .. py:method:: dtype(self)
      :property:


   .. py:method:: __nice__(self)


   .. py:method:: __getitem__(self, index)

      .. rubric:: References

      https://gis.stackexchange.com/questions/162095/gdal-driver-create-typeerror

      .. rubric:: Example

      >>> # Test nodata works correctly
      >>> # xdoctest: +REQUIRES(module:osgeo)
      >>> from kwcoco.util.lazy_frame_backends import *  # NOQA
      >>> from kwcoco.util.lazy_frame_backends import _demo_geoimg_with_nodata
      >>> fpath = _demo_geoimg_with_nodata()
      >>> self = LazyGDalFrameFile(fpath, nodata='auto')
      >>> imdata = self[:]
      >>> # xdoctest: +REQUIRES(--show)
      >>> import kwplot
      >>> import kwarray
      >>> kwplot.autompl()
      >>> imdata = kwimage.normalize_intensity(imdata)
      >>> imdata = np.nan_to_num(imdata)
      >>> kwplot.imshow(imdata)


   .. py:method:: __array__(self)

      Allow this object to be passed to np.asarray

      .. rubric:: References

      https://numpy.org/doc/stable/user/basics.dispatch.html



.. py:function:: _rectify_slice_dim(part, D)


.. py:function:: _validate_nonzero_data(file)

   Test to see if the image is all black.

   May fail on all-black images

   .. rubric:: Example

   >>> # xdoctest: +REQUIRES(module:osgeo)
   >>> import kwimage
   >>> gpath = kwimage.grab_test_image_fpath()
   >>> file = LazyGDalFrameFile(gpath)
   >>> _validate_nonzero_data(file)


.. py:function:: _read_envi_header(file)

   USAGE: hdr = _read_envi_header(file)

   Reads an ENVI ".hdr" file header and returns the parameters in a
   dictionary as strings.  Header field names are treated as case
   insensitive and all keys in the dictionary are lowercase.

   Modified from spectral/io/envi.py

   .. rubric:: References

   https://github.com/spectralpython/spectral