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, repetition_index=None)

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

   If repetition_index is None:
   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.

   If repetition_index is a valid integer,
   return the translation and rotation for that repeated physical volume 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)