Skip to content

shadow

shadow #

How far apart the shadows of two sun positions fall.

An upright pin one unit tall casts a shadow whose tip moves quickly when the sun is low and slowly near noon. Measuring sun positions by where that tip falls therefore spends more captures on the long, fast-changing shadows of morning and evening.

  1. Land. Find where the shadow's tip falls. On level ground, the tip is on the ground. In a square courtyard with walls of unlimited height, the tip stays on the ground until the shadow reaches a wall, then climbs that wall. The wall is unfolded flat, so a height on the wall continues the ground outward. On a wall, the tip reaches the pin's height at sunset and keeps climbing through twilight and night, so every sun position has a landing point.
  2. Compare. Measure the straight-line distance between two landing points. In a courtyard, the landing point moves at a bounded rate from sunrise through sunset and after.

ShadowDistanceFunction #

Bases: DistanceFunction[SolarPosition]

Distance between two pin-shadow tips, in pin heights, divided by sigma_heights.

Source code in capturegraph-recipes/capturegraph_recipes/scheduling/distance/shadow.py
class ShadowDistanceFunction(DistanceFunction[SolarPosition]):
    """Distance between two pin-shadow tips, in pin heights, divided by ``sigma_heights``."""

    def __init__(
        self,
        sigma_heights: float = 0.1,
        courtyard_heights: float | None = None,
    ) -> None:
        """Normalize by ``sigma_heights``; ``courtyard_heights`` as in ``shadow``."""
        self.sigma_heights = sigma_heights
        self.courtyard_heights = courtyard_heights

    def extract(self, values: cg.Array) -> np.ndarray:
        """Where each position's shadow tip lands, as ``(east, north)`` in pin heights.

        A row is ``nan`` for a missing position and, on level ground, for a sun below the horizon.
        """
        if self.courtyard_heights is not None:
            suns = np.array(
                [
                    (np.nan, np.nan) if cg.is_missing(value) else (value.altitude, value.azimuth)
                    for value in values
                ],
                dtype=np.float64,
            ).reshape(len(values), 2)
            return in_courtyard(suns[:, 0], suns[:, 1], self.courtyard_heights / 2.0)
        tips = [None if cg.is_missing(value) else value.shadow_tip for value in values]
        return np.array(
            [(np.nan, np.nan) if tip is None else tip for tip in tips],
            dtype=np.float64,
        ).reshape(len(tips), 2)

    def pairwise(self, features_a: np.ndarray, features_b: np.ndarray) -> np.ndarray:
        """The distances between two sets of landing points."""
        gap = features_a[:, None, :] - features_b[None, :, :]
        return np.hypot(gap[..., 0], gap[..., 1]) / self.sigma_heights

    def coverage(
        self,
        points: cg.Array | np.ndarray,
        captures: cg.Array | np.ndarray,
        weights: np.ndarray | None = None,
    ) -> np.ndarray:
        """As ``DistanceFunction.coverage``; unweighted, by each point's nearest tip alone."""
        if weights is not None:
            return super().coverage(points, captures, weights)
        point_features = self._features(points)
        tips = self._features(captures)
        tips = tips[~np.isnan(tips).any(axis=1)]
        if not len(tips):
            return np.zeros(len(point_features), dtype=np.float64)
        scores = np.zeros(len(point_features), dtype=np.float64)
        comparable = ~np.isnan(point_features).any(axis=1)
        nearest, _ = scipy.spatial.KDTree(tips).query(point_features[comparable])
        scores[comparable] = np.exp(-0.5 * (nearest / self.sigma_heights) ** 2)
        return scores

__init__(sigma_heights=0.1, courtyard_heights=None) #

Normalize by sigma_heights; courtyard_heights as in shadow.

Source code in capturegraph-recipes/capturegraph_recipes/scheduling/distance/shadow.py
def __init__(
    self,
    sigma_heights: float = 0.1,
    courtyard_heights: float | None = None,
) -> None:
    """Normalize by ``sigma_heights``; ``courtyard_heights`` as in ``shadow``."""
    self.sigma_heights = sigma_heights
    self.courtyard_heights = courtyard_heights

coverage(points, captures, weights=None) #

As DistanceFunction.coverage; unweighted, by each point's nearest tip alone.

Source code in capturegraph-recipes/capturegraph_recipes/scheduling/distance/shadow.py
def coverage(
    self,
    points: cg.Array | np.ndarray,
    captures: cg.Array | np.ndarray,
    weights: np.ndarray | None = None,
) -> np.ndarray:
    """As ``DistanceFunction.coverage``; unweighted, by each point's nearest tip alone."""
    if weights is not None:
        return super().coverage(points, captures, weights)
    point_features = self._features(points)
    tips = self._features(captures)
    tips = tips[~np.isnan(tips).any(axis=1)]
    if not len(tips):
        return np.zeros(len(point_features), dtype=np.float64)
    scores = np.zeros(len(point_features), dtype=np.float64)
    comparable = ~np.isnan(point_features).any(axis=1)
    nearest, _ = scipy.spatial.KDTree(tips).query(point_features[comparable])
    scores[comparable] = np.exp(-0.5 * (nearest / self.sigma_heights) ** 2)
    return scores

extract(values) #

Where each position's shadow tip lands, as (east, north) in pin heights.

A row is nan for a missing position and, on level ground, for a sun below the horizon.

Source code in capturegraph-recipes/capturegraph_recipes/scheduling/distance/shadow.py
def extract(self, values: cg.Array) -> np.ndarray:
    """Where each position's shadow tip lands, as ``(east, north)`` in pin heights.

    A row is ``nan`` for a missing position and, on level ground, for a sun below the horizon.
    """
    if self.courtyard_heights is not None:
        suns = np.array(
            [
                (np.nan, np.nan) if cg.is_missing(value) else (value.altitude, value.azimuth)
                for value in values
            ],
            dtype=np.float64,
        ).reshape(len(values), 2)
        return in_courtyard(suns[:, 0], suns[:, 1], self.courtyard_heights / 2.0)
    tips = [None if cg.is_missing(value) else value.shadow_tip for value in values]
    return np.array(
        [(np.nan, np.nan) if tip is None else tip for tip in tips],
        dtype=np.float64,
    ).reshape(len(tips), 2)

pairwise(features_a, features_b) #

The distances between two sets of landing points.

Source code in capturegraph-recipes/capturegraph_recipes/scheduling/distance/shadow.py
def pairwise(self, features_a: np.ndarray, features_b: np.ndarray) -> np.ndarray:
    """The distances between two sets of landing points."""
    gap = features_a[:, None, :] - features_b[None, :, :]
    return np.hypot(gap[..., 0], gap[..., 1]) / self.sigma_heights

in_courtyard(altitude, azimuth, half_width) #

Where the shadow of the pin's top lands in a courtyard for each sun, with the walls unfolded.

The shadow lands on the ground if it reaches the ground before the first wall in its path. Otherwise it meets that wall at height 1 - distance · tan(altitude), where distance runs from the pin to the wall along the shadow. This height exceeds the pin's once the sun is down, and it is added to the landing point along the wall's axis, away from the pin.

Parameters:

Name Type Description Default
altitude ndarray

Each sun's altitude, in degrees.

required
azimuth ndarray

Each sun's azimuth, in degrees.

required
half_width float

How far each wall stands from the pin, in pin heights.

required

Returns:

Type Description
ndarray

(east, north) per sun, in pin heights; nan where either angle is nan.

Source code in capturegraph-recipes/capturegraph_recipes/scheduling/distance/shadow.py
def in_courtyard(
    altitude: np.ndarray,
    azimuth: np.ndarray,
    half_width: float,
) -> np.ndarray:
    """Where the shadow of the pin's top lands in a courtyard for each sun, with the walls unfolded.

    The shadow lands on the ground if it reaches the ground before the first wall
    in its path. Otherwise it meets that wall at height
    ``1 - distance · tan(altitude)``, where ``distance`` runs from the pin to the
    wall along the shadow. This height exceeds the pin's once the sun is down,
    and it is added to the landing point along the wall's axis, away from the pin.

    Args:
        altitude: Each sun's altitude, in degrees.
        azimuth: Each sun's azimuth, in degrees.
        half_width: How far each wall stands from the pin, in pin heights.

    Returns:
        ``(east, north)`` per sun, in pin heights; ``nan`` where either angle is ``nan``.
    """
    rise, bearing = np.radians(altitude), np.radians(azimuth)
    away = np.column_stack([-np.sin(bearing), -np.cos(bearing)])
    rows = np.arange(len(away))
    wall = np.where(np.abs(away[:, 0]) >= np.abs(away[:, 1]), 0, 1)
    to_wall = half_width / np.abs(away[rows, wall])
    reach = np.full(len(away), np.inf)
    np.divide(1.0, np.tan(rise), out=reach, where=rise > 0.0)
    on_ground = reach <= to_wall
    landed = away * np.where(on_ground, reach, to_wall)[:, None]
    climb = np.where(on_ground, 0.0, 1.0 - to_wall * np.tan(rise))
    landed[rows, wall] += climb * np.sign(away[rows, wall])
    return landed

shadow(sigma_heights=0.1, courtyard_heights=None) #

Create a distance function over where an upright pin's shadow ends.

walled = cgr.scheduling.distance.shadow(sigma_heights=0.1, courtyard_heights=4.0)

Parameters:

Name Type Description Default
sigma_heights float

Normalization in pin heights: sun positions whose shadows end within sigma_heights of each other are within 1.0.

0.1
courtyard_heights float | None

The width of a square courtyard centred on the pin, in pin heights. A shadow that reaches a wall climbs it instead of continuing along the ground, so the distance stays defined through sunset and into the night. None means unbounded level ground.

None

Returns:

Type Description
ShadowDistanceFunction

A distance function (position_a, position_b) -> float. On level

ShadowDistanceFunction

ground, it is nan when either sun is below the horizon.

Source code in capturegraph-recipes/capturegraph_recipes/scheduling/distance/shadow.py
def shadow(
    sigma_heights: float = 0.1,
    courtyard_heights: float | None = None,
) -> ShadowDistanceFunction:
    """Create a distance function over where an upright pin's shadow ends.

    ```python
    walled = cgr.scheduling.distance.shadow(sigma_heights=0.1, courtyard_heights=4.0)
    ```

    Args:
        sigma_heights: Normalization in pin heights: sun positions whose shadows
            end within ``sigma_heights`` of each other are within 1.0.
        courtyard_heights: The width of a square courtyard centred on the pin,
            in pin heights. A shadow that reaches a wall climbs it instead of
            continuing along the ground, so the distance stays defined through
            sunset and into the night. ``None`` means unbounded level ground.

    Returns:
        A distance function ``(position_a, position_b) -> float``. On level
        ground, it is ``nan`` when either sun is below the horizon.
    """
    return ShadowDistanceFunction(sigma_heights, courtyard_heights)