Obscurations

class batoid.Obscuration[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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