test_unitSpacecraftLocation

test_unitSpacecraftLocation.test_spacecraftLocation(show_plots, defaultPolarRadius, defaultPlanet, latitude, maxRange, cone)

Tests whether spacecraftLocation:

1. defaults planet polar radius to equatorial radius if the polar radius is not set

2. checks that the zero default planet states are used if the planet is not provided

3. checks that the planet oblateness is accounted for

4. checks if the optional sensor boresight axis is properly accounted for

Returns:

test_unitSpacecraftLocation.test_spacecraftLocationColinearAccess(show_plots)

Regression test for issues #644 / #946.

Two spacecraft that are radially aligned (on the same ray from the planet center) at different altitudes have an unobstructed line of sight, so hasAccess must be 1.

Before the #946 fix (commit d432682135), rClose – the closest point on the inter-spacecraft segment to the planet center – was computed from the unclamped line parameter. For a radial alignment that parameter is negative, placing the “closest point” at the planet center (rClose ~ 0), so the rClose.norm() > rEquator gate failed and access was wrongly denied.

This geometry keeps every other access pathway neutral – no planet message (identity orientation at the origin), a spherical planet so zScale == 1, no range cap, no boresight cone, and no sun message – which isolates the rClose computation. The existing test_spacecraftLocation() cases cannot catch this regression: their equal-radius geometry holds the line parameter at ~0.5, inside [0, 1], where the clamp is a no-op.

test_unitSpacecraftLocation.test_spacecraftLocationGlare(caseName, sunPolarAngle, sunAzimuth, viewPolarAngle, viewAzimuth, expectedGlareFactor, glareThreshold, expectedHasGlare, useGlareConstraint, expectedAccess)

Verify specular-glare geometry and its optional access constraint.

Validation Test Description

The test places an offset body-fixed location far from the inertial origin, then supplies point-to-Sun and point-to-viewer directions with known mirror geometry. This verifies the glare factor, threshold flag, access behavior, and the use of the body-fixed location as the origin of both directions.

Test Parameter Discussion

The cases cover normal and oblique exact reflections, an in-plane near miss, an out-of-plane view, Sun and observer directions behind the surface, the exact threshold boundary, and zero-threshold back-facing geometry. useGlareConstraint also verifies that glare rejection is opt-in.

Expected Results

Exact reflections produce a glare factor of one. Off-specular and back-facing cases produce the analytical factor supplied by the test and do not meet the configured glare threshold. Back-facing geometry is never classified as glare, including when the threshold is zero.

test_unitSpacecraftLocation.test_spacecraftLocationGlareThresholdValidation(glareThreshold)

Verify that the geometric glare threshold is finite and in [0, 1].

Validation Test Description

The test initializes an otherwise valid module with a glare threshold outside the supported dimensionless alignment range or with a non-finite value.

Test Parameter Discussion

Values immediately below zero and above one exercise both invalid bounds. NaN and both infinities check that non-finite thresholds are rejected.

Expected Results

Reset() emits BSK_ERROR, which raises BasiliskError and stops initialization.

test_unitSpacecraftLocation.test_spacecraftLocationIlluminationRequirements(caseName, sunPolarAngle, solarAngleLimit, eclipseFactor, minimumIllumination, connectSun, connectEclipse, expectedIllumination, expectedAccess)

Verify the optional illumination-angle and eclipse requirements.

Validation Test Description

The test provides a surface point, its normal, a tracked imaging spacecraft, and optional Sun and eclipse messages. It evaluates the two illumination gates independently and together.

Test Parameter Discussion

The cases place the Sun inside or outside theta_solar, put the eclipse illumination factor above or below min_illumination_factor, omit the optional eclipse input, and omit the optional Sun input.

Expected Results

An illuminated point retains access only when every configured and connected illumination requirement is satisfied. Without a Sun message, illumination and glare remain unreported while geometric access is unchanged.

test_unitSpacecraftLocation.test_spacecraftLocationViewAngleRequirement(viewAngle, viewAngleLimit, connectSun, expectedAccess)

Verify the optional surface-normal-to-observer access requirement.

Validation Test Description

Place the tracked spacecraft at a known angle from the body-fixed normal, with and without the optional Sun message.

Test Parameter Discussion

The cases cover accepted and rejected views, the exact limit, and the negative default that disables the requirement.

Expected Results

scViewAngle reports the viewing geometry even without a Sun message. Access is denied only when the enabled viewing-angle limit is exceeded.

test_unitSpacecraftLocation.test_spacecraftLocationViewAngleRequiresNormal()

Verify that an enabled viewing-angle limit requires a surface normal.

Validation Test Description

Initialize a module with a viewing-angle limit but no aHat_B.

Test Parameter Discussion

A positive limit enables the otherwise optional viewing-angle check.

Expected Results

Reset() emits BSK_ERROR and initialization stops.

test_unitSpacecraftLocation.test_spacecraft_location_glare_multiple_observers(use_glare_constraint, sigma_BN)

Check independent glare outputs as two observers change position.

Validation Test Description

Connect two observers to an offset surface point. Start one at the ideal reflection and the other outside the glare cone, then swap their positions. Finally, move both outside the cone to check that each glare flag clears.

Test Parameter Discussion

Run with identity and nonzero primary attitudes and with glare rejection enabled and disabled. The Sun and observer directions are defined in the body frame and transformed into the inertial frame.

Expected Results

The observer on the reflected ray has unit glare factor. The other is twenty degrees away and has a glare factor below the default threshold. Each output follows its own observer at every update. Only the glared observer loses access when the constraint is enabled; previous glare flags do not persist once either observer leaves the reflected ray.

test_unitSpacecraftLocation.test_spacecraft_location_glare_roundoff(incidence_angle, sigma_BN, use_glare_constraint, view_offset, glare_threshold, expected_glare)

Verify glare thresholds at and just outside exact reflection geometry.

Validation Test Description

Construct the Sun direction and its ideal mirror reflection in the body frame, then rotate both into the inertial frame about an offset surface point. Shift the observer by a known angle from the ideal reflection.

Test Parameter Discussion

Incidence angles span normal through nearly grazing illumination, with identity and nonzero spacecraft attitudes. The cases exercise exact reflection at threshold one, the default threshold boundary, and views one microradian beyond each boundary. Glare rejection is enabled and disabled independently.

Expected Results

The glare factor equals the cosine of the reflected-ray viewing offset. Roundoff must not prevent boundary views from being classified as glare. Nearby views outside the boundary retain access, and detected glare only prevents access when the constraint is enabled.