find_limbs_surface

giant.ray_tracer.shapes.surface:

giant.ray_tracer.shapes.surface.find_limbs_surface(target, scan_center_dir, scan_dirs, observer_position=None, initial_step=None, max_iterations=25, rtol=1e-12, atol=1e-12)

This helper function determines the limb points for a surface (visible edge of the surface) that would be visible for an observer located at observer_position looking toward scan_center_dir along the directions given by scan_dirs.

Typically it is assumed that the location of the observer is at the origin of the current frame and therefore observer_position can be left as None.

The limb for the surface is found iteratively by tracing rays from the observer to the surface. First, the rays are traced along the scan center direction, which should beg guaranteed to strike the object. Then, we adjust the direction of the rays so that they no longer intersect the surface using initial_step (or 2 times the largest principal axis of the reference ellipse if initial_step is None). We then proceed by tracing rays with directions half way between the left rays (guaranteed to strike the surface) and the right rays (guaranteed to not strike the surface) updating the left and right rays based on the result of the last trace. This continues for a maximum of max_iterations or until the tolerances specified by rtol and atol are met for the change in the estimate of the limb location. The returned limb location is the last ray intersect location that hit the surface for each scan_dirs.

The returned limbs are expressed as vectors from the observer to the limb point in the current frame as a 3xn numpy array.

Note that this is specific to RawSurface surfaces and their subclasses (and is thus accelerated). For a general purpose find_limbs for any traceable object see the find_limbs() function in the utilities module.

Parameters:

  • target (Surface) – The target object that we are to find the limb points for as a Surface

  • scan_center_dir (ARRAY_LIKE) – the unit vector which the scan is to begin at in the current frame as a length 3 array A ray cast along this unit vector from the observer_position should be guaranteed to strike the surface and ideally should be towards the center of figure of the surface

  • scan_dirs (ARRAY_LIKE) – the unit vectors along with the scan is to proceed as a 3xn array in the current frame where each column represents a new limb point we wish to find (should be nearly orthogonal to the scan_center_dir in most cases).

  • observer_position (Optional[ARRAY_LIKE]) – The location of the observer in the current frame. If None then it is assumed the observer is at the origin of the current frame

  • initial_step (float) – The size of the initial step to take along the scan_dirs direction. This should be guaranteed to result in rays that do not strike the body.

  • max_iterations (int) – The maximum number of iteration steps to take when locating the limbs

  • rtol (float) – The relative tolerance of the change in the limb location from one iteration to the next that indicates convergence.

  • atol – the absolute tolerance of the change int he limb location from one iteration to the next that indicates convergence.

Returns:

the vectors from the observer to the limbs in the current frame as a 3xn array

Return type:

numpy.ndarray