cellmap_flow.portable.fill_calls
================================

.. py:module:: cellmap_flow.portable.fill_calls

.. autoapi-nested-parse::

   What the browser calls for Label it's box tools: the functions
   ``web/src/backend/routes/view-labels.ts``'s Seed from Prediction, All
   Background, Split Objects and Undo run through
   ``Inference.python("cellmap_flow.portable.fill_calls:<name>", args, arrays)``,
   in the shape ``chunkmirage.calls`` says: ``fn(args, arrays)``, ``args`` the
   JSON arguments, ``arrays`` the bytes sent beside them, in order; a JSON
   value, or a pair of JSON and arrays, back. Each decodes its arrays, calls
   ``fill.py`` and encodes the answer; the maths is not here, and the server's
   routes (``dashboard/routes/finetune/view_labels.py``, through
   ``finetune/session/fill.py``) call the same functions around MinIO.

   The route reads the box from the paint store and writes back what comes
   out, and keeps the undo stack, as the AI annotation's accept does
   (``ai_annotate_calls.accept``): nothing here reads or keeps a volume. A box
   travels as the store holds it: ``shape`` (z, y, x) and ``dtype`` (the
   volume's) in ``args``, its bytes in C order, always ``arrays[0]``. A write
   answers the box to write as its one array, or no array when nothing
   changes, so the route writes nothing and pushes no undo entry then.

   A refusal the server answers 400 (new ids that do not fit in the volume's
   dtype, a ValueError there) comes back as ``{"error": message}``, as
   ``label_it_calls`` answers its own, for the route to answer as the server
   does. A ``ModuleNotFoundError`` (scipy, which Split Objects labels its
   components with) is never caught: it is how chunkmirage's worker learns to
   load scipy, before it calls again.



Functions
---------

.. autoapisummary::

   cellmap_flow.portable.fill_calls.box
   cellmap_flow.portable.fill_calls.seed
   cellmap_flow.portable.fill_calls.background
   cellmap_flow.portable.fill_calls.split
   cellmap_flow.portable.fill_calls.undo


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

.. py:function:: box(args, arrays)

   The annotation voxels a box in world nm covers (``fill.box_voxels``).
   ``args``: ``volume`` (its ``output_voxel_size`` and
   ``dataset_offset_nm``), ``offset_nm`` and ``shape_nm`` (the box's lower
   corner and size, z, y, x) and ``volume_shape`` (the volume's voxels).
   Answers ``{"lo", "hi"}``, or null when no voxel of the volume is in the
   box.


.. py:function:: seed(args, arrays)

   A seed written into the box's unannotated voxels: ``fill.seed_labels``
   of the objects, written as ``fill.paint`` writes without overwrite.
   ``args``: the box's ``shape`` and ``dtype``, and ``instance_target``
   (the model trains on instances, so new ids count up on a volume of more
   than 8-bit ids: ``fill.counts_up``). ``arrays``: the box, then the
   objects over it (uint32, 0 background, as ``label_it_calls.seed``
   answers them). Answers the counts (``n_foreground``, ``n_background``,
   ``n_overwritten``) with the box to write; or the refusal, when the new
   ids do not fit.


.. py:function:: background(args, arrays)

   Every unannotated voxel of the box background (1), written as
   ``fill.paint`` writes without overwrite: All Background. ``args``: the
   box's ``shape`` and ``dtype``; ``arrays``: the box. Answers as
   ``seed``.


.. py:function:: split(args, arrays)

   The box's foreground relabelled by connected component
   (``fill.relabel_objects``) and written over its foreground voxels
   (``fill.rewrite``): Split Objects. ``args``: the box's ``shape`` and
   ``dtype``, and ``connectivity`` and ``per_slice``, as the route has read
   them. ``arrays``: the box. Answers the counts (``objects``, ``split``,
   ``merged``) and ``changed``, the voxels whose label changed, with the box
   to write; or the refusal, when the split-off pieces' new ids do not
   fit.


.. py:function:: undo(args, arrays)

   The box put back to before an action where it still holds what the
   action left (``fill.restore``): Undo. ``args``: the box's ``shape`` and
   ``dtype``; ``arrays``: the box as it is now, then the undo entry's
   ``before`` and ``after``, each shaped as the box. Answers ``restored``,
   the voxels put back, with the box to write.