Initial core implementation

This lacks integration with Makie but is otherwise reasonably functional.

Author: timholy

.github/workflows/CI.yml

@@ -24,8 +24,7 @@ jobs:
       matrix:
         version:
           - '1.10'
-          - '1.6'
-          - 'nightly'
+          - '1'
         os:
           - ubuntu-latest
         arch:

Project.toml

@@ -3,8 +3,12 @@ uuid = "c11bb9a7-2755-425a-88f3-ebe93bbdb91f"
 authors = ["Tim Holy <[email protected]> and contributors"]
 version = "1.0.0-DEV"
 
+[deps]
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+
 [compat]
-julia = "1.6.7"
+StaticArrays = "1"
+julia = "1.10"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

README.md

@@ -4,3 +4,157 @@
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://HolyLab.github.io/FlyThroughPaths.jl/dev/)
 [![Build Status](https://github.com/HolyLab/FlyThroughPaths.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/HolyLab/FlyThroughPaths.jl/actions/workflows/CI.yml?query=branch%3Amain)
 [![Coverage](https://codecov.io/gh/HolyLab/FlyThroughPaths.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/HolyLab/FlyThroughPaths.jl)
+
+
+All of the examples below assume you've loaded the package with `using FlyThroughPaths`.
+
+## Generic tools
+
+### Representation of paths and view state
+
+Paths are parametrized by time `t`, represented in units of seconds. All paths implicitly start at `t=0`.
+
+The representation of view state is independent of any particular plotting package, although our parametrization is inspired by [Makie's 3D camera](https://docs.makie.org/stable/explanations/cameras/#3d_camera):
+
+- `eyeposition`: the 3d coordinates of the camera
+- `lookat`: the 3d coordinates of the point of the camera's "focus" (center of gaze)
+- `upvector`: the 3d direction that will correspond to the top of the view. Any component of this vector in the direction of `lookat - eyeposition` is ignored/discarded.
+- `fov`: the angle (in degrees) of the cone centered on `lookat - eyeposition` that should be captured.
+
+Set these as follows:
+
+```julia
+julia> state = ViewState(eyeposition=[-10, 0, 0], lookat=[0, 0, 0], upvector=[0, 0, 1], fov=45)
+ViewState{Float32}(eyeposition=[-10.0, 0.0, 0.0], lookat=[0.0, 0.0, 0.0], upvector=[0.0, 0.0, 1.0], fov=45.0)
+```
+
+You can set just a subset of these:
+```julia
+julia> newstate = ViewState(eyeposition=[-5, 0, 0])
+ViewState{Float32}(eyeposition=[-5.0, 0.0, 0.0])
+```
+
+This syntax is often used for updating a previous view; for the unspecified settings, the previous value is left intact.
+
+
+### Initializing a path
+
+```julia
+julia> path = Path(state)
+Path{Float32}(ViewState{Float32}(eyeposition=[-10.0, 0.0, 0.0], lookat=[0.0, 0.0, 0.0], upvector=[0.0, 0.0, 1.0], fov=45.0), FlyThroughPaths.PathChange{Float32}[])
+```
+
+The path starts at `state` at time `t=0`.
+
+### Evaluating at a particular time
+
+Once you have a path, you can get the current `ViewState` with `path(t)`:
+
+```julia
+julia> path(0)
+ViewState{Float32}(eyeposition=[-10.0, 0.0, 0.0], lookat=[0.0, 0.0, 0.0], upvector=[0.0, 0.0, 1.0], fov=45.0)
+
+julia> path(10)
+ViewState{Float32}(eyeposition=[-10.0, 0.0, 0.0], lookat=[0.0, 0.0, 0.0], upvector=[0.0, 0.0, 1.0], fov=45.0)
+```
+
+So far, nothing much is happening. Things get more interesting when we add movements.
+
+### Holding steady
+
+The simplest thing you can do is insert a pause:
+
+```julia
+julia> path2 = path * Pause(5)
+Path{Float32}(ViewState{Float32}(eyeposition=[-10.0, 0.0, 0.0], lookat=[0.0, 0.0, 0.0], upvector=[0.0, 0.0, 1.0], fov=45.0), FlyThroughPaths.PathChange{Float32}[Pause{Float32}(5.0f0, nothing)])
+```
+
+The view will hold steady for 5 seconds. Typically you add `Pause` when you also plan to add other movements later.
+
+### Moving the camera, option 1: constrained movements
+
+This option is typically used for things like rotations around a center point.
+
+```julia
+julia> path2 = path * ConstrainedMove(5, newstate; constraint=:none, speed=:constant)
+Path{Float32}(ViewState{Float32}(eyeposition=[-10.0, 0.0, 0.0], lookat=[0.0, 0.0, 0.0], upvector=[0.0, 0.0, 1.0], fov=45.0), FlyThroughPaths.PathChange{Float32}[ConstrainedMove{Float32}(5.0f0, ViewState{Float32}(eyeposition=[-5.0, 0.0, 0.0]), :none, :constant, nothing)])
+```
+
+This indicates that over a 5-second period, the camera state gradually adopts any values specified in `newstate`.
+
+```julia
+julia> path2(0)
+ViewState{Float32}(eyeposition=[-10.0, 0.0, 0.0], lookat=[0.0, 0.0, 0.0], upvector=[0.0, 0.0, 1.0], fov=45.0)
+
+julia> path2(5)
+ViewState{Float32}(eyeposition=[-5.0, 0.0, 0.0], lookat=[0.0, 0.0, 0.0], upvector=[0.0, 0.0, 1.0], fov=45.0)
+
+julia> path2(2.5)
+ViewState{Float32}(eyeposition=[-7.5, 0.0, 0.0], lookat=[0.0, 0.0, 0.0], upvector=[0.0, 0.0, 1.0], fov=45.0)
+```
+
+Keyword options include:
+
+- `constraint` (`:none` or `:rotation`): specify a value to keep constant during motion. `:rotation` performs a rotation around `lookat`. Note that if the separation between `eyeposition` and `lookat` is not constant, then the trajectory will be elliptical rather than circular.
+- `speed` controls how the change is made across time:
+  - `:constant`: speed is instantaneously set to a new constant value that will arrive at the endpoint at the specified time
+  - `:sinusoidal`: speed will initially increase (starting at a speed of 0), achieve a maximum at the midpoint, and then decrease back to 0.
+
+
+### Moving the camera, option 2: Bezier movements
+
+With this option, you can approximately simulate the feeling of flight, preserving momentum:
+
+```
+path2 = path * BezierMove(Δt::Real, P1::ViewState, P2::ViewState...)
+```
+
+where a `bezier` path is specified as indicated in this diagram:
+
+![bezier diagram](https://upload.wikimedia.org/wikipedia/commons/thumb/d/d0/Bezier_curve.svg/640px-Bezier_curve.svg.png)
+
+The starting state, `P0` in the diagram, is taken from the endpoint of `path`. Over the next `Δt` seconds, one then moves towards the last `ViewState` argument of `bezier`, orienting successively towards any prior arguments. Probably the most robust option is to use `bezier(Δt, P1, P2, P3)`, which can be interpreted as "depart `P0` traveling towards `P1`, and arrive at `P3` as if you had come from `P2`." The view does not actually pass through `P1` and `P2`, but these set the initial and final tangents of the curve.
+
+To see this in action, let's create a move that "rotates" around the origin but moves outward (to a more distant orbit) on its way there:
+
+```julia
+julia> move = BezierMove(5, ViewState(eyeposition=[0, 10, 0]), [ViewState(eyeposition=[-20, 20, 0])])
+BezierMove{Float32}(5.0f0, ViewState{Float32}(eyeposition=[0.0, 10.0, 0.0]), ViewState{Float32}[ViewState{Float32}(eyeposition=[-20.0, 20.0, 0.0])], nothing)
+
+julia> path2 = path * move;
+
+julia> path2(2.5)
+ViewState{Float32}(eyeposition=[-12.5, 12.5, 0.0], lookat=[0.0, 0.0, 0.0], upvector=[0.0, 0.0, 1.0], fov=45.0)
+```
+
+## Backend-specific tools
+
+These require interaction with a plotting package supported by one of the extensions. Currently supported:
+
+- [Makie](https://docs.makie.org/stable/)
+
+You need to load the visualization package, e.g., `using GLMakie`, in your session before any of the commands below will work.
+
+### Capturing the current view state
+
+This can be handy for constructing a path, for example you can interactively set the approximate position and view parameters and then query them for use by the tools above.
+
+```
+state = capture_view(scene)
+```
+
+`state` is a `ViewState` object.
+
+### Setting the current view state
+
+```
+oldstate = set_view!(camera, path, t)
+```
+
+This updates the current `camera` settings from `path` at time `t`.
+
+### Displaying the path
+
+```
+plot(path)
+```

src/FlyThroughPaths.jl

@@ -1,5 +1,26 @@
 module FlyThroughPaths
 
-# Write your package code here.
+using StaticArrays
+
+export ViewState, Path, Pause, ConstrainedMove, BezierMove
+# exports for the extensions
+export capture_view, set_view!
+
+function capture_view end
+function set_view! end
+
+include("viewstate.jl")
+include("pathchange.jl")
+include("path.jl")
+
+function __init__()
+    if isdefined(Base.Experimental, :register_error_hint)
+        Base.Experimental.register_error_hint(MethodError) do io, exc, argtypes, kwargs
+            if exc.f === capture_view || exc.f === set_view!
+                print(io, '\n', exc.f, " requires that you first load a plotting backend (e.g., `using GLMakie`)")
+            end
+        end
+    end
+end
 
 end

src/path.jl

@@ -0,0 +1,25 @@
+struct Path{T}
+    initialview::ViewState{T}
+    changes::Vector{PathChange{T}}
+end
+Path{T}(initialview::ViewState) where T = Path{T}(initialview, PathChange{T}[])
+Path(initialview::ViewState{T}) where T = Path{T}(initialview)
+
+function Base.:*(path::Path{R}, change::PathChange{S}) where {R,S}
+    T = promote_type(R, S)
+    Path{T}(path.initialview, PathChange{T}[path.changes..., change])
+end
+
+function (path::Path{T})(t) where T
+    view = path.initialview
+    tend = zero(T)
+    t < tend && return view
+    for change in path.changes
+        tnext = tend + duration(change)
+        if t <= tnext
+            return change(view, t - tend)
+        end
+        tend, view = tnext, filldefaults(target(view, change), view)
+    end
+    return view
+end

src/pathchange.jl

@@ -0,0 +1,121 @@
+abstract type PathChange{T<:Real} end
+
+struct Pause{T} <: PathChange{T}
+    duration::T
+    action
+
+    function Pause{T}(t, action=nothing) where T
+        t >= zero(T) || throw(ArgumentError("t must be non-negative"))
+        new{T}(t, action)
+    end
+end
+Pause(duration::T) where T = Pause{T}(duration)
+
+Base.convert(::Type{Pause{T}}, p::Pause) where T = Pause{T}(p.duration, p.action)
+Base.convert(::Type{PathChange{T}}, p::Pause) where T = convert(Pause{T}, p)
+
+struct ConstrainedMove{T} <: PathChange{T}
+    duration::T
+    target::ViewState{T}
+    constraint::Symbol
+    speed::Symbol
+    action
+
+    function ConstrainedMove{T}(t, target, constraint, speed, action=nothing) where T
+        t >= zero(T) || throw(ArgumentError("t must be non-negative"))
+        constraint in (:none,:rotation) || throw(ArgumentError("Unknown constraint: $constraint"))
+        speed in (:constant,:sinusoidal) || throw(ArgumentError("Unknown speed: $speed"))
+        new{T}(t, target, constraint, speed, action)
+    end
+end
+ConstrainedMove{T}(duration, target; constraint=:none, speed=:constant, action=nothing) where T =
+    ConstrainedMove{T}(duration, target, constraint, speed, action)
+ConstrainedMove(duration, target::ViewState{T}, args...) where T = ConstrainedMove{T}(duration, target, args...)
+ConstrainedMove(duration, target::ViewState{T}; kwargs...) where T = ConstrainedMove{T}(duration, target; kwargs...)
+
+Base.convert(::Type{ConstrainedMove{T}}, m::ConstrainedMove) where T = ConstrainedMove{T}(m.duration, m.target, m.constraint, m.speed, m.action)
+Base.convert(::Type{PathChange{T}}, m::ConstrainedMove) where T = convert(ConstrainedMove{T}, m)
+
+struct BezierMove{T} <: PathChange{T}
+    duration::T
+    target::ViewState{T}
+    controls::Vector{ViewState{T}}
+    action
+
+    function BezierMove{T}(t, target, controls, action=nothing) where T
+        t >= zero(T) || throw(ArgumentError("t must be non-negative"))
+        new{T}(t, target, controls, action)
+    end
+end
+BezierMove(duration, target::ViewState{R}, controls::Vector{ViewState{S}}, args...) where {R,S} = BezierMove{promote_type(R,S)}(duration, target, controls, args...)
+
+Base.convert(::Type{BezierMove{T}}, m::BezierMove) where T = BezierMove{T}(m.duration, m.target, m.controls, m.action)
+Base.convert(::Type{PathChange{T}}, m::BezierMove) where T = convert(BezierMove{T}, m)
+
+# Common API
+
+duration(c::PathChange{T}) where T = c.duration::T
+
+target(oldtarget::ViewState{T}, c::PathChange{T}) where T = c.target::ViewState{T}
+target(oldtarget::ViewState{T},  ::Pause{T}) where T = oldtarget
+
+Base.@nospecializeinfer function act(@nospecialize(action), t::Real)
+    action === nothing && return nothing
+    action(t)
+    return nothing
+end
+
+# Compute the view from a PathChange at (relative) time t
+
+function (pause::Pause{T})(view::ViewState{T}, t) where T
+    checkt(t, pause)
+    action = pause.action
+    if action !== nothing
+        tf = t / duration(move)
+        act(action, tf)
+    end
+    return view
+end
+
+function (move::ConstrainedMove{T})(view::ViewState{T}, t) where T
+    checkt(t, move)
+    (; target, constraint, speed, action) = move
+    tf = t / duration(move)
+    f = speed === :constant ? tf : (1 - cospi(tf))/2
+    (; eyeposition, lookat, upvector, fov) = view
+    eyeposition_new = something(target.eyeposition, eyeposition)
+    lookat_new = something(target.lookat, lookat)
+    upvector_new = something(target.upvector, upvector)
+    fov_new = something(target.fov, fov)
+    lookatf = (1 - f) * lookat + f * lookat_new
+    if constraint === :none
+        eyeposition = (1 - f) * eyeposition + f * eyeposition_new
+    elseif constraint === :rotation
+        vold = eyeposition - lookat
+        vnew = eyeposition_new - lookat_new
+        eyeposition = cospi(f/2) * vold + sinpi(f/2) * vnew + lookatf
+    end
+    upvector = (1 - f) * upvector + f * upvector_new
+    fov = (1 - f) * fov + f * fov_new
+    lookat = lookatf
+    act(action, f)
+    return ViewState{T}(eyeposition, lookat, upvector, fov)
+end
+
+function (move::BezierMove{T})(view::ViewState{T}, t) where T
+    filldef(vs) = filldefaults(vs, view)
+    checkt(t, move)
+    tf = t / duration(move)
+    act(move.action, tf)
+    list = [view, filldef.(move.controls)..., filldef(move.target)]
+    return evaluate(list, tf)
+end
+
+# Recursive evaluation of bezier curves, https://en.wikipedia.org/wiki/B%C3%A9zier_curve#Recursive_definition
+function evaluate(list, t)
+    length(list) == 1 && return list[1]
+    return (1 - t) * evaluate(list[1:end-1], t) + t * evaluate(list[2:end], t)
+end
+
+@noinline checkt(t, change::PathChange{T}) where T = zero(T) <= t <= duration(change) ||
+    throw(ArgumentError("t=$t is not in [0, $(duration(change))]"))