opengate.geometry.utility
=========================

.. py:module:: opengate.geometry.utility


Functions
---------

.. autoapisummary::

   opengate.geometry.utility.box_add_size
   opengate.geometry.utility.cons_add_size
   opengate.geometry.utility.translate_point_to_volume
   opengate.geometry.utility.render_tree
   opengate.geometry.utility.is_rotation_matrix
   opengate.geometry.utility.vec_np_as_g4
   opengate.geometry.utility.vec_g4_as_np
   opengate.geometry.utility.rot_np_as_g4
   opengate.geometry.utility.rot_g4_as_np
   opengate.geometry.utility.ensure_is_g4_translation
   opengate.geometry.utility.ensure_is_g4_rotation
   opengate.geometry.utility.ensure_is_g4_transform
   opengate.geometry.utility.get_translation_from_rotation_with_center
   opengate.geometry.utility.get_transform_orbiting
   opengate.geometry.utility.get_transform_world_to_local
   opengate.geometry.utility.get_transform_world_to_local_old
   opengate.geometry.utility.get_circular_repetition
   opengate.geometry.utility.get_grid_repetition
   opengate.geometry.utility.volume_orbiting_transform


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

.. py:function:: box_add_size(box, thickness)

.. py:function:: cons_add_size(cons, thickness)

.. py:function:: translate_point_to_volume(simulation, volume, top, x)

   Consider the point x in the current volume and return the coordinate of x in the top volume
   (that must be an ancestor).
   Translation only, do not consider rotation.


.. py:function:: render_tree(tree, geometry, world_name)

   Print a tree of volume


.. py:function:: is_rotation_matrix(R)

   https://stackoverflow.com/questions/53808503/how-to-test-if-a-matrix-is-a-rotation-matrix


.. py:function:: vec_np_as_g4(v)

.. py:function:: vec_g4_as_np(v)

.. py:function:: rot_np_as_g4(rot)

.. py:function:: rot_g4_as_np(rot)

.. py:function:: ensure_is_g4_translation(translation)

.. py:function:: ensure_is_g4_rotation(rotation)

.. py:function:: ensure_is_g4_transform(translation=(0, 0, 0), rotation=Rotation.identity().as_matrix())

.. py:function:: get_translation_from_rotation_with_center(rot, center)

.. py:function:: get_transform_orbiting(initial_position, axis, angle_deg)

.. py:function:: get_transform_world_to_local(volume)

   Calculate the rotation and translation needed
   to transform from the world reference frame
   into the local reference frame of this volume.

   Returns two lists, the first with translation vectors,
   the second with rotation matrices. Each list entry corresponds
   to one physical volume of the Gate volume, i.e. one repetition.
   For non-repeated volumes, the lists will contain one item only.


.. py:function:: get_transform_world_to_local_old(vol_name)

.. py:function:: get_circular_repetition(number_of_repetitions, first_translation, angular_step_deg='auto_full_circle', start_angle_deg=0.0, additional_rotation=Rotation.identity().as_matrix(), axis=(0, 0, 1))

   Generate translations and rotations to repeat volumes in a circle.

   This helper function generates translations and rotations for a volume to be repeated in a circle,
   e.g. in a PET ring. The returned lists with translations and rotations can be used as input to the translation
   and rotation parameter of any repeatable volume in Gate.

   Args:
       number_of_repetitions (int) : How many times should the volume be repeated?
       first_translation (3-vector) : Where should the first copy of the volume be placed (wrt. to the mother volume)?
       angular_step_deg (float, optional) : The angular step in degrees between subsequent repetitions.
           Accepts a number or two special arguments, 'auto_full_circle' and 'auto_half_circle',
           to determine the angular step automatically. Default: 'auto_full_circle'
       start_angle_deg (int, optional) : The angle at which the repetition starts.
           The first volume copy is placed at `first_translation` and then rotated by `start_angle_deg`.
           Default: 0.
       additional_rotation (3x3 rotation matrix, optional) : Additional rotation to be applied to all copies,
           e.g. if the volume is tilted. Default: 3x3 identity.
       axis (3-vector, optional) : The axis (in the mother's frame of reference) around which
           the circular repetition is performed. Default: [0, 0, 1], i.e. z-axis, circle in the x-y-plane.

   Returns:
       list : A list of translation vectors, one for each repetition.
       list : A list of rotation matrices, one for each repetition.


.. py:function:: get_grid_repetition(size, spacing, start=None, return_lut=False)

   Generate a list of 3-vectors to be used as 'translation' parameter of a repeated volume.

   Args:
       size (list, np.ndarray) : 3-item list or numpy array specifying the number of repetitions
           along the axes x, y, z.
       spacing (list, np.ndarray) : 3-item list or numpy array specifying the spacing along the axes x, y, z
           between the translation vectors.
       start (optional): Optional 3-item list or numpy array specifying the first translation vector on the grid.
           If not provided, the grid is centered around (0,0,0).
       return_lut (bool, optional) : If true, the functions also returns a dictionary mapping copy index
           to the respective translation vector for later reference.

   Returns:
       list : A list of translations vectors.
       dict : (Optional) A dictionary mapping copy index to the respective translation vector. Only if `return_lut` is `True`.


.. py:function:: volume_orbiting_transform(axis, start, end, n, initial_t, initial_rot)