box
===

.. py:module:: 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::

   box.Axes
   box.BoxInternal
   box.Box


Functions
---------

.. autoapisummary::

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


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

.. py:class:: Axes

   .. py:attribute:: ROW
      :value: 0



   .. py:attribute:: COL
      :value: 1



   .. py:attribute:: DEPTH
      :value: 2



.. py:class:: BoxInternal(row_start, row_stop, col_start, col_stop, depth_start=None, depth_stop=None, 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:attribute:: depth_start
      :value: None



   .. py:attribute:: depth_stop
      :value: None



   .. 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, height) of a box if 2d data, else returns (width, height, depth)



   .. py:method:: corners()

      Return (Wstart, Wstop, Hstart, Hstop) of current box if 2d data, else returns (Wstart, Wstop, Hstart, Hstop. Dstart, Dstop)



   .. py:method:: __1d_parts()


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


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

      Create 4 boxes from the original box passed in as an argument.
      Pick two axes to split on randomly using the Axes class and create boxes.



   .. py:method:: create_box(axes, c1, box)

      Create a box depending on the selected axis and the random coordinate
      This will create 2 boxes from the original box passed in as an argument.
      params:
          axes: The axis to split on
          c1: The random coordinate to split on
          box: The original box to split on



   .. 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, depth_start=None, depth_stop=None, 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, d_start=None, d_lim=None)

   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 or 6-tuple depending on whether the box is 2D or 3D.

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


.. py:function:: boxes_name_and_dimensions(boxes)

   Returns a list of all boxes and their dimensions