vkframes: spacecraft trajectory visualization for modern Fortran

What it is

OpenFrames' ideas, rebuilt for Fortran and Vulkan

vkframes is heavily inspired by OpenFrames, the OpenSceneGraph-based library behind the visualizations of tools such as NASA's GMAT and Copernicus. It covers OpenFrames' features, but its API is designed for Fortran from the start: derived types with type-bound procedures, double-precision arrays, optional arguments and no hidden global state.

Underneath, a thin C++ layer drives VulkanSceneGraph and Vulkan; everything else (the scene, the math, the data) lives in Fortran. Your program owns its objects, and the scene holds pointers to them.

Experimental. vkframes is under active development: the API changes without notice and some features are incomplete. It is developed mainly on macOS.

Doubleprecision throughout: lines relative to the eye and reverse-Z depth, so a 10 m spacecraft and an Earth orbit share one view.
Livescenes: add, change and remove anything while it is shown. Only changed data is uploaded.
GPUanimation: fading trails, highlights and level of detail are drawn by shaders, not recomputed on the CPU.
Embedin your own GUI: Qt through qt-fortran, Python through PySide6, or vkframes' own windows.

What you can do

Everything a mission visualization needs

⌖

Reference frames

A tree of frames with positions, attitudes (quaternions), axes and labels. Follow any frame, or look from one frame toward another.

●

Bodies

Spheres and exact ellipsoids with day and night textures, lighting and twilight; 3D models through vsgXchange; terrain and imagery through Rocky.

∿

Trajectories

Curves with dash patterns, markers, segments, ribbons, per-point colors, trace mode and fading trails that show the past and future around the current time.

☉

Lighting & shadows

A frame can be the Sun: day and night sides, city lights, specular glints, and shadow cones (umbra, penumbra, antumbra) that follow the bodies.

✦

The sky

The HYG star catalog sized and colored by brightness, a sky texture, star names and constellation lines, all at infinity behind the scene.

✛

Reference shapes

Coordinate axes with ticks, latitude/longitude grids, radial planes, sensor cones, polyhedra and surfaces, and lines of sight computed each frame.

☝

Picking & handles

Pick trajectories, markers and bodies under the mouse. Drag velocity arrows or a trajectory's end to design orbits graphically, in real time.

▶

Cameras & video

Smooth camera flights between views, synchronized clocks across windows, screenshots, and video recording straight to ffmpeg at a steady frame rate.

▣

GUIs

Dear ImGui panels drawn in the scene, HUD text and callouts that follow objects, and windows embedded in Qt or PySide6 applications.

Gallery

Made with vkframes

Every image here is a vkframes example or demo, captured from the running program. Click one to see it larger.

Tycho crater on the Moon, with terrain — Tycho crater from LRO imagery and LOLA elevation, through Rocky.

Shadow cones in a solar eclipse — A solar eclipse: the Moon's umbra reaching the Earth inside its penumbra.

Orbits colored along their length — Colors per point: a Molniya orbit by altitude, a low orbit by sunlight.

Star names and constellation lines behind the Earth — The sky: stars, their names and the constellations, behind the scene.

Orbit planes swept out from the Earth's center — Orbit planes swept from the Earth's center as the spacecraft move.

Halo orbit manifolds — An Earth–Moon halo orbit's invariant manifold tubes, with an ImGui panel.

Dragging the velocity arrow to design an orbit — Designing an orbit by dragging its velocity arrow, recomputed as you drag.

Thrust vectors along an orbit transfer, at an adjustable scale.

The Earth's day and night sides — The Sun as a light: city lights on the night side and a specular glint.

Reference shapes around the Earth — A latitude/longitude grid, a radial plane, tick-marked axes and sensor cones.

Rendezvous and proximity operations — Rendezvous in the target's LVLH frame: keep-out sphere and approach corridor.

The Earth-Moon CR3BP — The Earth–Moon three-body problem in the rotating frame.

An Earth-to-Mars transfer during optimization — An Earth-to-Mars transfer, a solver's iterations played back.

Fading trails: past solid, future dashed — Fading trails: the past solid and fading, the future dashed, drawn by the GPU.

A lander descending into Tycho crater — A lander descending into Tycho, its altitude above the terrain in its label.

A lunar flyby in inertial coordinates — One free-return lunar flyby in two windows at once: inertial about the Earth, and Moon-fixed about the Moon.

The same lunar flyby in the Moon-fixed frame — One free-return lunar flyby in two windows at once: inertial about the Earth, and Moon-fixed about the Moon.

A small program

A scene in a few dozen lines

The Earth, a spacecraft on an inclined circular orbit, and the orbit drawn as a line. Objects are plain Fortran variables: declare them target, connect them into a tree, and run the frame loop.

How the objects connect hover a box to find it in the code

windowWindowProxy
- earth_viewViewlooks at earth
- sceneFrameManager
  - earthSphere
    - craftSpherefollows orbit
    - orbit_frameDrawableTrajectory
      - orbit_lineCurveArtistdraws orbit

orbitTrajectorytimes and positions, shared by craft and orbit_line

window & view
frames
artists
data

orbit_demo.f90

program orbit_demo
    use vkframes
    implicit none
    real(wp), parameter :: re = 6378.137_wp, inc = 50.0_wp * pi / 180.0_wp
    type(Sphere), target :: earth, craft
    type(Trajectory), target :: orbit
    type(DrawableTrajectory), target :: orbit_frame
    type(CurveArtist), target :: orbit_line
    type(FrameManager), target :: scene
    type(WindowProxy), target :: window
    type(View), target :: earth_view
    real(wp) :: t, a
    integer :: k

    earth = Sphere('Earth', radius=re)
    call earth%set_texture_map('2k_earth_daymap.jpg')
    craft = Sphere('Spacecraft', radius=300.0_wp, color=[1.0_wp, 0.3_wp, 0.2_wp])

    ! a circular orbit inclined 50 degrees, over one period
    orbit = Trajectory()
    do k = 0, 360
        t = 600.0_wp * k / 360.0_wp
        a = 2.0_wp * pi * t / 600.0_wp
        call orbit%add(t, pos=1.6_wp * re * [cos(a), sin(a)*cos(inc), sin(a)*sin(inc)])
    end do
    call craft%follow(orbit)

    ! the orbit drawn as a line
    orbit_line = CurveArtist(orbit, color=[1.0_wp, 0.8_wp, 0.2_wp], width=2.0_wp)
    orbit_frame = DrawableTrajectory('Orbit')
    call orbit_frame%add_artist(orbit_line)
    if (.not. (earth%add_child(craft) .and. earth%add_child(orbit_frame))) error stop
    scene = FrameManager(earth)

    if (.not. window%open(800, 600, 'vkframes')) error stop
    call window%set_scene(scene)
    earth_view = View(earth, earth)
    call earth_view%set_default_view_distance(2.5_wp * re)
    call window%add_view(earth_view)
    do while (window%frame())     ! until the window is closed
    end do
    call window%close()
end program orbit_demo

Get started

Up and running in minutes

Install pixi, which brings the Fortran and C++ compilers, VulkanSceneGraph and every other dependency. Then, from the repository:

$ git clone https://github.com/jacobwilliams/vkframes
$ cd vkframes
$ pixi run build
$ pixi run example orbit_demo

More than twenty examples (pixi run example <name>) and a set of demos, including Qt and PySide6 GUIs, show each feature.

Platforms

Where it runs

Main
macOSApple silicon, macOS 26 or later. The main development platform.
Builds
Windows x64Builds and runs; less tested.
Tested
Linux x64Built and tested in CI and in a Docker container (Ubuntu, software Vulkan); not yet tested on real GPUs.

Open source

Open, top to bottom

vkframes is free and open source, under the Apache License 2.0: use it, change it and ship it in your own programs, commercial ones included.

It is built entirely on an open-source, cross-platform foundation: the Vulkan standard, VulkanSceneGraph and vsgXchange, glslang, Dear ImGui, gfortran and fpm, all installed from conda-forge by pixi. On macOS it draws through KosmicKrisp, Mesa's open-source Vulkan driver for Metal. Nothing proprietary is needed to build or run it.

Apache 2.0 vkframes' license Read the license

Built on

Modern graphicsfor Modern Fortran.

OpenFrames' ideas, rebuilt for Fortran and Vulkan

Everything a mission visualization needs

Reference frames

Bodies

Trajectories

Lighting & shadows

The sky

Reference shapes

Picking & handles

Cameras & video

GUIs

Made with vkframes

A scene in a few dozen lines

Up and running in minutes

Where it runs

Open, top to bottom

Modern graphics
for Modern Fortran.