Obscurations — batoid 0.4.2 documentation

# Obscurations

class batoid.Obscuration

  An `Obscuration` instance is used to mark as vignetted (i.e., obscured) if their x/y coordinates lie in a particular region.

  `Obscuration` s are useful for modeling pupils, clear apertures of optical elements, struts, or other physical obstructions in an optical system. Note that only the x and y local coordinates of rays are considered; the z coordinate is ignored.

  contains(x, y)

    Return True if the point (x,y) is obscured.

    Parameters:

      x, y (float) – X/Y coordinates of point in meters.

    Returns:

      obscured (bool) – True if point is obscured. False otherwise.

  obscure(rv)

    Mark rays for potential vignetting.

    Parameters:

      rv (`RayVector`) – Rays to analyze.

    Returns:

      out (`RayVector`) – Returned object will have appropriate elements marked as vignetted.

class batoid.ObscCircle(radius, x=0.0, y=0.0)

  Bases: `Obscuration`

  A circular obscuration.

  Parameters:

    - radius (float) – Radius of circle in meters.

    - x, y (float, optional) – Coordinates of circle center in meters. [default: 0.0]

class batoid.ObscAnnulus(inner, outer, x=0.0, y=0.0)

  Bases: `Obscuration`

  An annular obscuration.

  Parameters:

    - inner (float) – Inner radius of annulus in meters.

    - outer (float) – Outer radius of annulus in meters.

    - x, y (float, optional) – Coordinates of annulus center in meters. [default: 0.0]

class batoid.ObscRectangle(width, height, x=0.0, y=0.0, theta=0.0)

  Bases: `Obscuration`

  A rectangular obscuration.

  Parameters:

    - width (float) – Width (X-extent) of rectangle in meters.

    - height (float) – Height (Y-extent) of rectangle in meters.

    - x, y (float, optional) – Coordinates of rectangle center in meters. [default: 0.0]

    - theta (float, optional) – Counter-clockwise rotation of rectangle in radians. [default: 0.0]

class batoid.ObscRay(width, theta, x=0.0, y=0.0)

  Bases: `Obscuration`

  A finite-width ray-like obscuration.

  (Like a rectangle, but infinitely long in one direction.)

  Parameters:

    - width (float) – Width of ray obscuration in meters.

    - theta (float) – Rotation angle of ray in radians.

    - x, y (float, optional) – Coordinates of ray origin in meters. [default: 0.0]

class batoid.ObscNegation(original)

  Bases: `Obscuration`

  A negated obscuration.

  The originally obscured regions become clear, and the originally clear regions become obscured.

  Parameters:

    original (`Obscuration`) – The obscuration to negate.

class batoid.ObscUnion(*items)

  Bases: `Obscuration`

  A union of `Obscuration` s.

  Parameters:

    *items (`Obscuration` s) – The `Obscuration` s to unionize.

  Examples

  Though not very useful, one could in principle unionize a circle and an annulus to make a larger circle:

      >>> small_circle = batoid.ObscCircle(1.0)
      >>> annulus = batoid.ObscAnnulus(1.0, 2.0)
      >>> big_circle = batoid.ObscCircle(2.0)
      >>> alternate_big_circle = batoid.ObscUnion(small_circle, annulus)

  Using a list or tuple is also okay with `ObscUnion`.

      >>> other_alternate_big_circle = batoid.ObscUnion([small_circle, annulus])

  Although `big_circle` and `alternate_big_circle` will not compare equal above, their behavior with respect to obscuring rays is the same:

      >>> rays = batoid.RayVector.asGrid(
              backDist=10.0, wavelength=500e-9, nx=10, lx=4.0, dirCos=(0,0,1)
          )
      >>> obsc1 = big_circle.obscure(rays)
      >>> obsc2 = alternate_big_circle.obscure(rays)
      >>> obsc1 == obsc2
      True

class batoid.ObscIntersection(*items)

  Bases: `Obscuration`

  An intersection of `Obscuration` s.

  Parameters:

    *items (`Obscuration` s) – The `Obscuration` s to intersect.

  Examples

  An alternate way to create an annulus is the intersection of a large circle and a negated small circle.

      >>> big_circle = batoid.ObscCircle(2.0)
      >>> small_circle = batoid.ObscCircle(1.0)
      >>> annulus = batoid.ObscAnnulus(1.0, 2.0)
      >>> alternate_annulus = batoid.ObscIntersection(
              batoid.ObscNegation(small_circle),
              big_circle
          )

  Using a list or tuple is also okay with `ObscIntersection`.

      >>> other_alternate_annulus = batoid.ObscIntersection([
              batoid.ObscNegation(small_circle),
              big_circle
          ])

  Although `annulus` and `alternate_annulus` will not compare equal above, their behavior with respect to obscuring rays is the same:

      >>> rays = batoid.RayVector.asGrid(
              backDist=10.0, wavelength=500e-9, nx=10, lx=4.0, dirCos=(0,0,1)
          )
      >>> obsc1 = annulus.obscure(rays)
      >>> obsc2 = alternate_annulus.obscure(rays)
      >>> obsc1 == obsc2
      True