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.