across.tools.visibility

Submodules

• across.tools.visibility.base
• across.tools.visibility.catalogs
• across.tools.visibility.constraints
• across.tools.visibility.constraints_constructor
• across.tools.visibility.ephemeris_visibility
• across.tools.visibility.joint_visibility

Attributes

Constraints

Classes

Visibility	Abstract base class for visibility calculations.
Constraint	Model for deserializing a single constraint.
EphemerisVisibility	A class for calculating visibility windows based on ephemeris data and constraints.
JointVisibility	Computes joint visibility windows between multiple instruments.

Functions

constraints_from_json(input)	Load constraints from a JSON string.
constraints_to_json(constraints)	Convert constraints to a JSON string.
compute_ephemeris_visibility(begin, end, ephemeris, ...)	Compute visibility windows based on ephemeris data and constraints.
compute_joint_visibility(visibilities, instrument_ids)	Compute joint visibility windows for any number of instrument Visibilities.

Package Contents

class Visibility(/, **data)

Bases: abc.ABC, across.tools.core.schemas.base.BaseSchema

Abstract base class for visibility calculations.

Parameters:

• ra – Right ascension of the target in degrees.

• dec – Declination of the target in degrees.

• coordinate – SkyCoord object representing the position of the target in sky coordinates. Optional if ra and dec are provided.

• begin – Start time of visibility period.

• end – End time of visibility period.

• step_size – Time step size for visibility calculations. Default is 60 seconds.

• min_vis – Minimum visibility duration in seconds for a window to be included. Default is 0.

• observatory_id – Unique Observatory ID for which this visibility is calculated.

• observatory_name – Name of the observatory for which this visibility is calculated.

timestamp

Array of time values used in the visibility calculation.

inconstraint

Boolean array indicating whether the target is not constrained at each time step.

calculated_constraints

Ordered dictionary mapping constraint types to boolean arrays.

visibility_windows

List of visibility windows computed from the constraints.

computed_values

Container (VisibilityComputedValues) providing access to geometric quantities calculated during visibility analysis. After running a visibility calculation, you can inspect these values for further analysis or visualization. Fields include:

• sun_angle: Angular separation between target and Sun (Quantity array)

• moon_angle: Angular separation between target and Moon (Quantity array)

• earth_angle: Angular separation between target and Earth limb (Quantity array)

• alt_az: Altitude-azimuth coordinates of target from observatory (SkyCoord)

Not all fields are populated for every calculation; values are only computed and stored by constraints that need them.

visible(t)

Check if the target is visible at a given time.

compute()

Perform visibility calculation.

ra: float | None = None

dec: float | None = None

step_size: across.tools.core.schemas.AstropyTimeDelta

coordinate: astropy.coordinates.SkyCoord | None = None

begin: across.tools.core.schemas.AstropyDateTime

end: across.tools.core.schemas.AstropyDateTime

min_vis: int = 0

observatory_id: uuid.UUID = None

observatory_name: str

timestamp: across.tools.core.schemas.AstropyDateTime | None = None

inconstraint: numpy.typing.NDArray[numpy.bool_] = None

calculated_constraints: collections.OrderedDict[across.tools.core.enums.constraint_type.ConstraintType, numpy.typing.NDArray[numpy.bool_]] = None

visibility_windows: list[across.tools.core.schemas.VisibilityWindow] = []

computed_values: across.tools.core.schemas.visibility.VisibilityComputedValues = None

classmethod validate_parameters(values)

Validate and synchronize SkyCoord, RA and DEC values. This method ensures that both coordinate representations (SkyCoord object and separate RA/DEC values) are present and consistent. If one representation is missing, it is computed from the other. In addition, it validates the step size and ensures it is a positive value. The begin and end times are rounded to the nearest step size, to ensure consistency.

Parameters:

values (dict[str, float | astropy.coordinates.SkyCoord]) – Dictionary containing the input values to validate, including coordinate, ra, dec, step_size, begin, and end.

Return type:

Validated and synchronized dictionary of values.

visible(t)

For a given time or array of times, is the target visible?

Parameters:

t (astropy.time.Time) – Time to check

Return type:

True if visible, False if not

_compute_timestamp()

Compute timestamp array for visibility calculation. The base implementation is to create a timestamp array from the begin and end times with a step size defined by the step_size attribute.

_quantize_to_step(t)

Quantize a time to the nearest configured step size relative to begin.

index(t)

For a given time, return the index in the ephemeris.

Parameters:

t (astropy.time.Time) – Time to find the index for

Return type:

Index of the nearest time in the ephemeris

abstract _constraint(i)

For a given index, return the constraint at that time.

Parameters:

i (int) – Index in the timestamp array.

Return type:

The constraint type at the given index.

abstract _merge_computed_values()

Abstract method to merge computed values from constraints.

abstract prepare_data()

Abstract method to perform visibility calculation.

_get_id(i)

For a given index, get the ID of the observatory or instrument.

Parameters:

i (int) – Index in the timestamp array.

Return type:

The observatory or instrument ID.

_get_name(i)

For a given index, get the name of the observatory or instrument.

Parameters:

i (int) – Index in the timestamp array.

Return type:

The observatory or instrument name.

_make_windows()

Create visibility windows from the inconstraint array.

Return type:

List of VisibilityWindow objects representing periods when the target is visible.

plot(fig=None, offset=0, width=700, height=1000)

Method to visualize visibility windows using plotly. Calls the across-tools plotting core functionality and configures the plot layout to user specifications.

Parameters:

• fig (go.Figure, optional) – An existing plotly figure to add to, by default None

• offset (int | float, optional) – The x-axis offset to plot new visibility windows, by default 0

• width (int, optional) – The width of the plot, in pixels. Defaults to 700

• height (int, optional) – The height of the plot, in pixels. Defaults to 1000

Returns:

The plotly figure containing the footprint plot

Return type:

go.Figure

compute()

Perform visibility calculation.

class Constraint(/, **data)

Bases: pydantic.BaseModel

Model for deserializing a single constraint.

root: across.tools.visibility.constraints.AllConstraint

classmethod unwrap_input(data)

Unwrap input data to extract constraint.

serialize_constraint()

Serialize the constraint to a dictionary.

Constraints: pydantic.TypeAdapter[list[across.tools.visibility.constraints.AllConstraint]]

constraints_from_json(input)

Load constraints from a JSON string.

Parameters:

input (str) – JSON string containing the constraints.

Returns:

Single Constraint object or list of Constraint objects loaded from the JSON string.

Return type:

AllConstraint | list[AllConstraint]

constraints_to_json(constraints)

Convert constraints to a JSON string.

Parameters:

constraints (AllConstraint | list[AllConstraint]) – Single Constraint object or list of Constraint objects to convert.

Returns:

JSON string representation of the constraints.

Return type:

str

class EphemerisVisibility(/, **data)

Bases: across.tools.visibility.base.Visibility

A class for calculating visibility windows based on ephemeris data and constraints. This class extends the base Visibility class to compute visibility periods using ephemeris data and multiple constraints. It processes time series data to determine when specified constraints are met and generates visibility windows accordingly.

Parameters:

• constraints (ObservatoryConstraints) – List of constraint objects to be evaluated

• timestamp (Time) – Array of time points for visibility calculations

• calculated_constraints (dict[str, np.typing.NDArray[np.bool_]]) – Dictionary mapping constraint names to boolean arrays of evaluation results

• inconstraint (np.typing.NDArray[np.bool_]) – Boolean array indicating combined constraint evaluation results

• ephemeris (Ephemeris | None) – Ephemeris data object containing spacecraft position/timing information

• step_size (int) – Time step size in seconds for calculations (60s for high res, 3600s for low res)

get_ephemeris_vis()

Calculates visibility windows based on ephemeris data and constraints

constraint(index)

Determines which constraint is active at a given time index

make_windows(inconstraint)

Generates visibility window objects from boolean constraint data

Notes

The class processes ephemeris data against multiple constraints to determine periods of visibility. It handles both high and low resolution timing and generates windows with start/end times and constraint information.

ephemeris: across.tools.ephemeris.base.Ephemeris = None

constraints: list[across.tools.visibility.constraints.base.ConstraintABC] = None

classmethod normalize_constraints(v)

Normalize single constraint to list.

prepare_data()

Query visibility for given parameters.

Return type:

True if successful, False otherwise.

_compute_timestamp()

Compute timestamp array for visibility calculation.

This method is called to ensure that the timestamp array is set before any visibility calculations are performed.

_merge_computed_values()

Merge computed values from all constraints into the main computed_values attribute.

_find_violated_constraint(constraint, index)

Find which actual constraint is violated at a given index.

For logical constraints (And/Or/Not/Xor), recursively check sub-constraints to find the actual constraint that caused the violation.

Parameters:

• constraint (across.tools.visibility.constraints.base.ConstraintABC) – The constraint to check (may be logical or regular)

• index (int) – Index of timestamp to check

Return type:

The ConstraintType of the violated constraint

_constraint(index)

What kind of constraints are in place at a given time index.

Parameters:

index (int) – Index of timestamp to check

Return type:

String indicating what constraint is in place at given time index

compute_ephemeris_visibility(begin, end, ephemeris, constraints, ra=None, dec=None, coordinate=None, step_size=60 * u.s, observatory_name='Observatory', observatory_id=None, min_vis=0)

Compute visibility windows based on ephemeris data and constraints.

Parameters:

• ra (float | None) – Right Ascension in degrees, if applicable.

• dec (float | None) – Declination in degrees, if applicable.

• coordinate (SkyCoord | None) – SkyCoord object representing the position in the sky, if applicable.

• ephemeris (Ephemeris) – The ephemeris data to use for visibility calculations.

• constraints (Sequence[ConstraintABC]) – List of constraints to apply for visibility calculations.

• begin (Time) – Start time for visibility calculation.

• end (Time) – End time for visibility calculation.

• step_size (u.Quantity, optional) – Step size for the timestamp array, default is 60 seconds.

• observatory_name (str, optional) – Name of the observatory for which visibility is calculated, default is “Observatory”.

• observatory_id (UUID, optional) – Unique identifier for the observatory, if available.

• min_vis (int, optional) – Minimum visibility time for a window to be considered valid, default is 0 seconds.

Returns:

An instance of EphemerisVisibility with computed visibility windows.

Return type:

EphemerisVisibility

class JointVisibility(/, **data)

Bases: across.tools.visibility.base.Visibility, Generic[T]

Computes joint visibility windows between multiple instruments.

This class takes a list of Visibility objects with identical timestamp grids and computes the intersection of their visibility periods.

Parameters:

• visibilities (list[T]) – List of Visibility or Visibility child objects with identical timestamp grids.

• instrument_ids (list[UUID]) – List of IDs of the instruments belonging to the Visibility objects.

visibilities: list[T] = None

instrument_ids: list[uuid.UUID] = None

step_size: across.tools.core.schemas.AstropyTimeDelta = None

begin: across.tools.core.schemas.AstropyDateTime = None

end: across.tools.core.schemas.AstropyDateTime = None

observatory_name: str = None

classmethod validate_parameters(values)

Validate and synchronize coordinate, begin/end, and step size values. This method ensures that all the input Visibility objects have the same coordinates, begin and end times, and step sizes. If any of these values differ between Visibilities, a ValueError is raised. When these equalities have been validated, this method runs the base Visibility validate_parameters method to validate other parameter values.

_constraint(i)

For a given index, return the constraint from the first visibility that is actually constrained.

_get_id(i)

For a given index, find the observatory ID of the first visibility that is constrained.

_get_name(i)

For a given index, get the name of the first instrument that is constrained.

prepare_data()

Compute joint visibility by ANDing all inconstraint arrays.

Raises:

ValueError – If visibilities list is empty or if visibilities have different timestamp grids.

_merge_computed_values()

Abstract method to merge computed values from constraints.

plot(fig=None, offset=0, width=700, height=1000)

Method to visualize joint visibility windows using plotly. Plots the individual instrument visibility windows and the regions of joint visibility on one figure. Calls the across-tools plotting core functionality and configures the plot layout to user specifications.

Parameters:

• fig (go.Figure, optional) – An existing plotly figure to add to, by default None

• offset (int | float, optional) – The x-axis offset to plot new visibility windows, by default 0

• width (int, optional) – The width of the plot, in pixels. Defaults to 700.

• height (int, optional) – The height of the plot, in pixels. Defaults to 1000.

Returns:

The plotly figure containing the footprint plot

Return type:

go.Figure

compute_joint_visibility(visibilities, instrument_ids, min_vis=0)

Compute joint visibility windows for any number of instrument Visibilities. Assumes that the visibilities are in the same order as instrument_ids.

Parameters:

• visibilities (list[T]) – List of Visibility objects or children objects of Visibility.

• instrument_ids (list[UUID]) – List of IDs of the instruments belonging to the Visibility objects.

• min_vis (int, optional) – Minimum visibility duration in seconds for a window to be included. Default is 0.

Returns:

List of VisibilityWindows capturing joint visibility between all inputted instruments.

Return type:

list[VisibilityWindow]