API Reference

abstract type AbstractKiteViewer

All kite viewers must inherit from this type. All methods that are defined on this type must work with all kite viewers. All exported methods must work on this type.

const AKV = AbstractKiteViewer

Short alias for the AbstractKiteViewer.

Viewer3D <: AbstractKiteViewer

Mutable struct representing a 3D kite power system viewer, built on GLMakie.

Holds the Makie figure, 3D scene, camera, screen, particle/tether geometry observables, settings, UI buttons, optional menus, and simulation bookkeeping (step counter, energy, stop flag, etc.).

The seg_topology/wing_*/point_positions fields are nothing until init_segments sets up rendering of an arbitrary point/segment topology (used for the V3 kite); positions/ markersizes/rotation are then reused (resized) for the tether+bridle layer, the wing_* triple backs a second, black-colored layer for the wing segments, and point_positions backs a third layer of small spheres sized for a dense point cloud — the built-in part_positions sphere marker is sized for the sparse legacy topologies and is too large not to overlap into a solid blob on a 44-point kite.

Use the outer constructors Viewer3D(show_kite, autolabel; precompile) or Viewer3D(set, show_kite, autolabel; precompile, menus) to create an instance.

SegmentType

The three kinds of segment a topology matrix passed to init_segments can contain, rendered respectively as a thick yellow cylinder (TETHER), a thin yellow cylinder (BRIDLE), and a thin black cylinder (WING).

clear_viewer(kv::AKV; stop_=true)

Reset the viewer to its initial state by setting the step counter to 1 and the accumulated energy to zero. By default, the simulation is also stopped (status set to "Stopped" and running set to false). Pass stop_=false to reset the counters without stopping.

Arguments

• kv::AKV: the kite viewer instance.

Keyword Arguments

• stop_=true: whether to call stop(kv) after resetting.

update_system(kv::AKV, state::SysState; scale=1.0, kite_scale=1.0, ned=true, 
              wind=[:v_wind_200m, :v_wind_kite])

Update the 3D visualization of the kite power system, including the tether, kite, and status text.

Moves all tether segment particles and the kite to their new positions based on the given system state, recalculates cylinder positions, sizes, and rotations for the tether rendering, updates the kite orientation, and refreshes the on-screen status text (time, height, elevation, azimuth, forces, power, energy, wind, etc.).

Supports one-point, four-point, and three-line (four-point 3L) kite models.

Arguments

• kv::AKV: the kite viewer instance.
• state::SysState: the current system state containing positions, orientation, and flight data.

Keyword Arguments

• scale=1.0: scaling factor applied to all particle positions.
• kite_scale=1.0: additional scaling factor for the kite relative to the pod/bridle attachment point.
• ned=true: if true, convert the orientation quaternion from NED to viewer convention.
• wind=[:v_wind_200m, :v_wind_kite]: list of wind fields to display in the status text. Supported symbols: :v_wind_gnd, :v_wind_200m, :v_wind_kite.

update_status_text!(kv::AKV, state::SysState; height=state.Z[end], wind=[:v_wind_200m, :v_wind_kite])

Refresh the on-screen status text (time, height, elevation, azimuth, forces, power, energy, wind) from state. Shared by update_system, which passes the topology-specific height it already computed, and update_segments!-based replay, which has no such convention and should pass whichever state.Z slot best represents the kite's height.

Keyword Arguments

• height=state.Z[end]: height value to display [m].
• wind=[:v_wind_200m, :v_wind_kite]: list of wind fields to display in the status text. Supported symbols: :v_wind_gnd, :v_wind_200m, :v_wind_kite.

save_png(viewer; filename="video", index=1)

Save the current viewer frame as a PNG file in the video/ directory.

The output file is named <filename><index>.png, where index is zero-padded to six digits (e.g. video000001.png). The video/ directory is created if it does not exist.

Keyword Arguments

• filename="video": prefix for the output file name.
• index=1: frame number, zero-padded to six digits in the file name.

stop(kv::AKV)

Stop the simulation. Sets the viewer's stop flag to true, updates the status text to "Stopped", and sets running to false.

pause(kv::AKV)

Pause the simulation. Sets the viewer's stop flag to true, saves the current status text in last_status, and updates the status to "Paused".

set_status(kv::AKV, status_text)

Set the viewer status text to status_text. If the new status is not "Paused", the current status is saved in last_status before updating.

copy_examples()

Copy all example scripts to the folder "examples" (it will be created if it doesn't exist).

init_segments(kv::AKV, segments::AbstractMatrix{<:Integer})

Set up kv to render an arbitrary point/segment topology instead of the built-in one-point/ four-point/three-line kite models — used to replay a V3 kite log. segments is an n × 3 integer matrix of (point1, point2, segment_type), one row per segment, with segment_type one of the SegmentType values; load it from a CSV with load_segments.

Tether and bridle segments reuse the viewer's built-in yellow tether layer (kv.positions/ kv.markersizes/kv.rotation, resized), with tether segments rendered thicker than bridle segments; wing segments get a new black layer. The built-in point-sphere layer (kv.part_positions) is hidden and replaced by a new layer with a much smaller marker, sized for a dense point cloud — except on the points of the main tether, which keep a bead twice their cylinder's radius so its segmentation stays readable. Call update_segments! every frame afterwards to move the points.

load_segments(filename) -> Matrix{Int64}

Read a segment topology CSV like data/v3_segments.csv (columns segment,point1,point2, segment_type; the first column is ignored, it is just the row number) into the n × 3 integer matrix expected by init_segments: (point1, point2, segment_type), with segment_type mapped from the strings "tether"/"bridle"/"wing" onto the SegmentType values.

update_segments!(kv::AKV, state::SysState; scale=1.0, kite_scale=1.0)

Update a viewer set up with init_segments to the point positions in state: moves the point spheres and recomputes every segment's cylinder midpoint, length and orientation from the topology passed to init_segments. Only positions 1:n_points of state.X/Y/Z are used — extra slots (VSM panel corners, wing/body origins) are ignored.

Unlike update_system, this does not touch the kite mesh, quaternion, or status text; call update_status_text! separately if needed.

Keyword Arguments

• scale=1.0: scaling factor applied to all point positions.
• kite_scale=1.0: extra scaling of bridle and wing, so a small kite stays visible next to a long tether. The centre is the end of the main tether — its only point shared with a bridle or wing segment, the KCU — which keeps the tether itself untouched and grows the bridle with the wing, the same convention as update_system. A topology whose tether ends nowhere falls back to the centroid of the scaled points.

segment_geometry(points, rows, radius_of)

Cylinder midpoint, (radius, radius, length) markersize, and unit-vector rotation for each segment in rows (a n × 3 slice of (point1, point2, segment_type)), reading endpoints from points. radius_of(segment_type) returns the relative radius for a segment type. Shared by the two segment layers update_segments! writes to.