rex_xai.box
===========

.. py:module:: rex_xai.box

.. autoapi-nested-parse::

   generate boxes which together create a occlusion.
   This occlusion is realised in the form of a mask over an image



Classes
-------

.. autoapisummary::

   rex_xai.box.BoxInternal
   rex_xai.box.Box


Functions
---------

.. autoapisummary::

   rex_xai.box.initialise_tree
   rex_xai.box.show_tree
   rex_xai.box.average_box_size
   rex_xai.box.box_dimensions
   rex_xai.box.boxes_name_and_dimensions


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

.. py:class:: BoxInternal(row_start, row_stop, col_start, col_stop, distribution=None, distribution_args=None, name='')

   a box is part of an occulsion, a collection of boxes which form a mask over an image


   .. py:attribute:: name
      :value: ''



   .. py:attribute:: distribution
      :value: None



   .. py:attribute:: distribution_args
      :value: None



   .. py:attribute:: row_start
      :type:  int


   .. py:attribute:: row_stop
      :type:  int


   .. py:attribute:: col_start
      :type:  int


   .. py:attribute:: col_stop
      :type:  int


   .. py:method:: __repr__()


   .. py:method:: __hash__()


   .. py:method:: __eq__(other)


   .. py:method:: update_name(name)

      sets the name of a box



   .. py:method:: shape()

      returns (width, heigh) of a box



   .. py:method:: corners()

      Return (Wstart, Wstop, Hstart, Hstop) of current box



   .. py:method:: __1d_parts()


   .. py:method:: __2d_parts(map=None)


   .. py:method:: spawn_children(min_size, mode, map=None)

      spawn subboxes from <self>



   .. py:method:: area()

      returns the area of a box



.. py:class:: Box(row_start, row_stop, col_start, col_stop, distribution=None, distribution_args=None, name='', parent=None, children=None)

   Bases: :py:obj:`BoxInternal`, :py:obj:`anytree.NodeMixin`


   An object that represents a box, a set of
   boxes forms an occlusion


   .. py:attribute:: parent
      :value: None


      Parent Node.

      On set, the node is detached from any previous parent node and attached
      to the new node.

      >>> from anytree import Node, RenderTree
      >>> udo = Node("Udo")
      >>> marc = Node("Marc")
      >>> lian = Node("Lian", parent=marc)
      >>> print(RenderTree(udo))
      Node('/Udo')
      >>> print(RenderTree(marc))
      Node('/Marc')
      └── Node('/Marc/Lian')

      **Attach**

      >>> marc.parent = udo
      >>> print(RenderTree(udo))
      Node('/Udo')
      └── Node('/Udo/Marc')
          └── Node('/Udo/Marc/Lian')

      **Detach**

      To make a node to a root node, just set this attribute to `None`.

      >>> marc.is_root
      False
      >>> marc.parent = None
      >>> marc.is_root
      True


   .. py:attribute:: children
      :value: ()


      All child nodes.

      >>> from anytree import Node
      >>> n = Node("n")
      >>> a = Node("a", parent=n)
      >>> b = Node("b", parent=n)
      >>> c = Node("c", parent=n)
      >>> n.children
      (Node('/n/a'), Node('/n/b'), Node('/n/c'))

      Modifying the children attribute modifies the tree.

      **Detach**

      The children attribute can be updated by setting to an iterable.

      >>> n.children = [a, b]
      >>> n.children
      (Node('/n/a'), Node('/n/b'))

      Node `c` is removed from the tree.
      In case of an existing reference, the node `c` does not vanish and is the root of its own tree.

      >>> c
      Node('/c')

      **Attach**

      >>> d = Node("d")
      >>> d
      Node('/d')
      >>> n.children = [a, b, d]
      >>> n.children
      (Node('/n/a'), Node('/n/b'), Node('/n/d'))
      >>> d
      Node('/n/d')

      **Duplicate**

      A node can just be the children once. Duplicates cause a :any:`TreeError`:

      >>> n.children = [a, b, d, a]
      Traceback (most recent call last):
          ...
      anytree.node.exceptions.TreeError: Cannot add node Node('/n/a') multiple times as child.


   .. py:method:: add_children_to_tree(min_size, mode, map)

      adds a list of boxes (children) to box tree



.. py:function:: initialise_tree(r_lim, c_lim, distribution, distribution_args, r_start=0, c_start=0)

   initialise box tree with root node, the whole image


.. py:function:: show_tree(tree)

   Print the box tree to the terminal.


.. py:function:: average_box_size(tree, d)

   Calculate the average box size at depth <d> of <tree>.


.. py:function:: box_dimensions(box)

   Returns box dimensions as a 4-tuple.

   @param box: Box
   @return (int, int, int, int)


.. py:function:: boxes_name_and_dimensions(boxes)

   Returns a list of all boxes and their dimensions