:py:mod:`kwcoco.coco_image`
===========================

.. py:module:: kwcoco.coco_image


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

Classes
~~~~~~~

.. autoapisummary::

   kwcoco.coco_image.CocoImage



Functions
~~~~~~~~~

.. autoapisummary::

   kwcoco.coco_image._delay_load_imglike



.. py:class:: CocoImage(img, dset=None)

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

   An object-oriented representation of a coco image.

   It provides helper methods that are specific to a single image.

   This operates directly on a single coco image dictionary, but it can
   optionally be connected to a parent dataset, which allows it to use
   CocoDataset methods to query about relationships and resolve pointers.

   This is different than the Images class in coco_object1d, which is just a
   vectorized interface to multiple objects.

   .. rubric:: Example

   >>> import kwcoco
   >>> dset1 = kwcoco.CocoDataset.demo('shapes8')
   >>> dset2 = kwcoco.CocoDataset.demo('vidshapes8-multispectral')

   >>> self = CocoImage(dset1.imgs[1], dset1)
   >>> print('self = {!r}'.format(self))
   >>> print('self.channels = {}'.format(ub.repr2(self.channels, nl=1)))

   >>> self = CocoImage(dset2.imgs[1], dset2)
   >>> print('self.channels = {}'.format(ub.repr2(self.channels, nl=1)))
   >>> self.primary_asset()

   .. py:method:: from_gid(cls, dset, gid)
      :classmethod:


   .. py:method:: __nice__(self)

      .. rubric:: Example

      >>> from kwcoco.coco_image import *  # NOQA
      >>> import kwcoco
      >>> with ub.CaptureStdout() as cap:
      ...     dset = kwcoco.CocoDataset.demo('shapes8')
      >>> self = CocoImage(dset.dataset['images'][0], dset)
      >>> print('self = {!r}'.format(self))

      >>> dset = kwcoco.CocoDataset.demo()
      >>> self = CocoImage(dset.dataset['images'][0], dset)
      >>> print('self = {!r}'.format(self))


   .. py:method:: stats(self)

      


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


   .. py:method:: keys(self)


   .. py:method:: get(self, key, default=ub.NoParam)

      Duck type some of the dict interface


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


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


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


   .. py:method:: primary_asset(self, requires=[])

      Compute a "main" image asset.

      :Parameters: **requires** (*List[str]*) -- list of attribute that must be non-None to consider an object
                   as the primary one.

      .. todo:: - [ ] Add in primary heuristics


   .. py:method:: iter_asset_objs(self)

      Iterate through base + auxiliary dicts that have file paths


   .. py:method:: delay(self, channels=None, space='image', bundle_dpath=None)

      Experimental method

      :Parameters: * **gid** (*int*) -- image id to load
                   * **channels** (*FusedChannelSpec*) -- specific channels to load.
                     if unspecified, all channels are loaded.
                   * **space** (*str*) -- can either be "image" for loading in image space, or
                     "video" for loading in video space.

      .. todo::

         - [X] Currently can only take all or none of the channels from each
             base-image / auxiliary dict. For instance if the main image is
             r|g|b you can't just select g|b at the moment.
         
         - [X] The order of the channels in the delayed load should
             match the requested channel order.
         
         - [ ] TODO: add nans to bands that don't exist or throw an error
         
         - [ ] This function could stand to have a better name. Maybe imread
               with a delayed=True flag? Or maybe just delayed_load?

      .. rubric:: Example

      >>> from kwcoco.coco_image import *  # NOQA
      >>> import kwcoco
      >>> gid = 1
      >>> #
      >>> dset = kwcoco.CocoDataset.demo('vidshapes8-multispectral')
      >>> self = CocoImage(dset.imgs[gid], dset)
      >>> delayed = self.delay()
      >>> print('delayed = {!r}'.format(delayed))
      >>> print('delayed.finalize() = {!r}'.format(delayed.finalize()))
      >>> print('delayed.finalize() = {!r}'.format(delayed.finalize(as_xarray=True)))
      >>> #
      >>> dset = kwcoco.CocoDataset.demo('shapes8')
      >>> delayed = dset.delayed_load(gid)
      >>> print('delayed = {!r}'.format(delayed))
      >>> print('delayed.finalize() = {!r}'.format(delayed.finalize()))
      >>> print('delayed.finalize() = {!r}'.format(delayed.finalize(as_xarray=True)))

      >>> crop = delayed.delayed_crop((slice(0, 3), slice(0, 3)))
      >>> crop.finalize()
      >>> crop.finalize(as_xarray=True)

      >>> # TODO: should only select the "red" channel
      >>> dset = kwcoco.CocoDataset.demo('shapes8')
      >>> delayed = CocoImage(dset.imgs[gid], dset).delay(channels='r')

      >>> import kwcoco
      >>> gid = 1
      >>> #
      >>> dset = kwcoco.CocoDataset.demo('vidshapes8-multispectral')
      >>> delayed = dset.delayed_load(gid, channels='B1|B2', space='image')
      >>> print('delayed = {!r}'.format(delayed))
      >>> print('delayed.finalize() = {!r}'.format(delayed.finalize(as_xarray=True)))
      >>> delayed = dset.delayed_load(gid, channels='B1|B2|B11', space='image')
      >>> print('delayed = {!r}'.format(delayed))
      >>> print('delayed.finalize() = {!r}'.format(delayed.finalize(as_xarray=True)))
      >>> delayed = dset.delayed_load(gid, channels='B8|B1', space='video')
      >>> print('delayed = {!r}'.format(delayed))
      >>> print('delayed.finalize() = {!r}'.format(delayed.finalize(as_xarray=True)))

      >>> delayed = dset.delayed_load(gid, channels='B8|foo|bar|B1', space='video')
      >>> print('delayed = {!r}'.format(delayed))
      >>> print('delayed.finalize() = {!r}'.format(delayed.finalize(as_xarray=True)))

      .. rubric:: Example

      >>> import kwcoco
      >>> dset = kwcoco.CocoDataset.demo()
      >>> coco_img = dset.coco_image(1)
      >>> # Test case where nothing is registered in the dataset
      >>> delayed = coco_img.delay()
      >>> final = delayed.finalize()
      >>> assert final.shape == (512, 512, 3)



.. py:function:: _delay_load_imglike(bundle_dpath, obj)