Skip to content

Guidance Figures#

A participant decides when and where to capture by looking at the app, so a study shows them what its dataset still needs. A guidance figure is an image a target serves into an image slot of its schema: drawn on the server with cgui.Figure, memoized by the captures and the time it was drawn for, and refreshed by a background interceptor.

The figures share one reading. Teal is what the captures so far cover; along what is coming, orange is still needed and grey is already covered. Coverage is DistanceFunction.coverage, so "covered" means within a sigma of a capture under the same metric the scheduler uses.

Layer Draws
coverage_field(axes, covered, extent, inside=None) Coverage on a grid over the chart's plane, as a teal wash, optionally clipped to an outline.
coming_path(axes, xy, need, marks=()) Where the coming conditions travel through the chart, grey to orange by need, its start ringed as now, a dot at each mark.
need_timeline(axes, instants, need, now=None) Need by clock time, in the zone the instants carry; each peak timed, the past faded.
basemap(axes, locations) A muted OpenStreetMap street map framed around the places; returns the projection from latitude and longitude onto the chart. Each tile is fetched once and kept.
from datetime import timedelta

import capturegraph as cg
import capturegraph_recipes as cgr
import capturegraph_ui as cgui
import numpy as np

guidance = cgr.scheduling.guidance
forecast = cgr.scheduling.forecast


@cg.pure_function("sun_guidance/1")
def sun_guidance(
    site: cg.Location,
    photographed: cg.Array[cg.Time],
    start: cg.Time,
) -> cg.Image:
    sun = cgr.scheduling.distance.solar(sigma_deg=4.0)
    taken = forecast.solar_position(site, cg.Array([when.value for when in photographed]))
    coming = forecast.solar_position(
        site,
        forecast.times(timedelta(minutes=5), timedelta(hours=24), start.value),
    )
    with cgui.Figure("Sun over the next 24 hours") as figure:
        xy = np.column_stack([coming.azimuth, coming.altitude])
        xy[xy[:, 1] <= 0] = np.nan
        guidance.coming_path(figure.axes, xy, 1.0 - sun.coverage(coming, taken))
        figure.axes.set_xlabel("Sun azimuth (°)")
        figure.axes.set_ylabel("Sun altitude (°)")
        figure.axes.legend()
    return figure.image

A target serves it from a background interceptor keyed by the hour, so the app shows the last figure at once while the next one draws:

@cgserver.intercept(Study, lambda s: s.guidance.sun, dynamic=False, background=True)
def serve_sun(target: Study) -> cg.Image:
    return sun_guidance(SITE, target.sessions.keys(), cg.Time.now(every=timedelta(hours=1)))

Keep a figure to one message: a short title, a legend, axes — the explanation of what it means belongs on the study's page, not in the image.