cellmap_flow.models.geometry
============================

.. py:module:: cellmap_flow.models.geometry

.. autoapi-nested-parse::

   A model's geometry: what it reads and writes, and at what voxel size.

   The inference server, blockwise, the server's ``model_info`` and the
   dashboard's geometry cache each read these numbers off ``ModelConfig.config``
   one attribute at a time, with their own conversions. ``ModelGeometry`` is
   them, read once: sizes in nm as given (whole numbers as ints, so 5.24 nm
   stays 5.24), and the shapes in voxels, the context and the block shape
   derived from them.

   ``from_config`` reads anything with the config attributes: a built config, or
   the stand-ins ``serving.client`` and ``models.geometry_cache`` build from a
   server's ``model_info`` or the cache, which carry no block shape.

   Importing this module is cheap: numpy, funlib.geometry and io.ome only.



Attributes
----------

.. autoapisummary::

   cellmap_flow.models.geometry.DEFAULT_OUTPUT_AXES


Classes
-------

.. autoapisummary::

   cellmap_flow.models.geometry.ModelGeometry


Functions
---------

.. autoapisummary::

   cellmap_flow.models.geometry.number
   cellmap_flow.models.geometry.channel_names_of


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

.. py:data:: DEFAULT_OUTPUT_AXES
   :value: ('c', 'z', 'y', 'x')


.. py:function:: number(value)

   ``value`` as an int when it is whole, else as a float.

   ``int()`` truncated a 5.24 nm voxel size to 5, which put crops and
   layers on the wrong grid.


.. py:function:: channel_names_of(config)

   The channel names a config gives, as a tuple, or None: the first
   non-empty one of channels, channels_names (Hugging Face), classes, or a
   ModelGeometry's channel_names. A string is one name, so
   ``channels = "mito"`` is ``("mito",)``.


.. py:class:: ModelGeometry

   What a model reads and writes. Sizes are in nm unless named ``*_shape`` in voxels.


   .. py:attribute:: input_voxel_size
      :type:  Tuple[float, ...]


   .. py:attribute:: output_voxel_size
      :type:  Tuple[float, ...]


   .. py:attribute:: read_shape
      :type:  Tuple[float, ...]


   .. py:attribute:: write_shape
      :type:  Tuple[float, ...]


   .. py:attribute:: output_channels
      :type:  int


   .. py:attribute:: channel_names
      :type:  Optional[Tuple[str, ...]]
      :value: None



   .. py:attribute:: chunk_output_axes
      :type:  Tuple[str, ...]
      :value: ('c', 'z', 'y', 'x')



   .. py:attribute:: output_dtype
      :type:  Optional[numpy.dtype]
      :value: None



   .. py:attribute:: input_channels
      :type:  int
      :value: 1



   .. py:attribute:: declared_block_shape
      :type:  Optional[Tuple[int, ...]]
      :value: None



   .. py:property:: ndim
      :type: int


      Spatial dimensions.


   .. py:property:: input_shape
      :type: Tuple[int, ...]


      Voxels the model reads.


   .. py:property:: output_shape
      :type: Tuple[int, ...]


      Voxels the model writes.


   .. py:property:: context
      :type: funlib.geometry.Coordinate


      nm read beyond the written region on each side.

      funlib arithmetic, as the Inferencer and blockwise always computed
      it: Coordinate truncates each size to an int, and ``/`` floors.


   .. py:property:: has_channel_axis
      :type: bool


      Whether a chunk the model outputs has a channel axis.


   .. py:method:: block_shape() -> Tuple[int, ...]

      (*spatial, channels) of one output block: the declared one, if any.



   .. py:method:: from_config(config, chunk_output_axes=None, output_dtype=None) -> ModelGeometry
      :classmethod:


      From ``ModelConfig.config``, or anything with its geometry attributes.

      ``chunk_output_axes`` and ``output_dtype``, when given, win over the
      config's own (``ModelConfig`` passes its properties, with their
      defaults); otherwise the config's are used, if it has them.



   .. py:method:: to_model_info(spatial_axes=None, actual_input_voxel_size=None) -> dict

      The geometry keys of the server's ``/__control__/model_info``.

      ``spatial_axes``: the served array's, which are the raw data's (the
      spatial axes of chunk_output_axes by default). ``output_axes`` is
      them in order, then "c" when the output has a channel axis.

      ``actual_input_voxel_size``: what the input really is. When it is
      not input_voxel_size, the data was read at another level as if it
      were at input_voxel_size, voxel for voxel, so an output voxel really
      is ``actual_in * output_voxel_size / input_voxel_size``: that is
      ``effective_output_voxel_size``, otherwise output_voxel_size. The
      served .zattrs still say output_voxel_size.