README.md

Fibre

Fibre is a WebGL application for visualizing and coding 3d vector fields and dynamical systems. A number of presets with well-known or interesting dynamical systems are provided as below (click to launch). New vector fields can be authored in the code editor, and shared via an HTML link with the embedded code.

In three (or more) dimensions, a non-linear continuous dynamical system may exhibit chaos, which is characterised by sensitive dependence of the solution trajectories to the initial conditions, and evolution governed by a so-called "strange attractor". Probably the most famous example is the Lorenz system, initially discovered as a simplified model of atmospheric convection:

whose solution curves (x(t), y(t), z(t)), starting from any initial point (x(0), y(0), z(0)), tend to the Lorenz strange attractor.

In general, a three-dimensional continuous dynamical system is a system of first order ordinary differential equations (ODE) of the form below, where the functions on the right hand side define a vector field giving the velocity vector of the dynamical system at each point in space (and, optionally, time):

In Fibre, the code editor on the left specifies this velocity vector field via the GLSL function vec3 velocity(vec3 p, float t) . Additionally, a color at each point in space must be specified via vec3 color(vec3 p, float t). The system then traces the solution curves of the ODE (using the Runge-Kutta method), starting from a grid of points covering the "initial conditions box" positioned in the viewport. These curves are rendered as colored tubes. (Note, the tubes are not rendered as geometry, they consist of many individual line segments, which are progressively rendered and blended over a number of iterations in order to converge to the final image).

UI controls:

• left-click mouse to rotate, right-click mouse to pan camera
• hover over the initial conditions box and left-click to drag it around, or hover over the box corners and left-click to resize the box dimensions. The box extents can also be edited directly in the Integrator rollout of the UI.
• the first (green) ☰ button hides/shows the code editor, in which the velocity vector field and color field are defined as GLSL functions.
• editing the GLSL code immediately updates the shader -- if there is an error, this will be copied to the viewport, and rendering terminated
• click on values in the code editor to pop up a slider which scrubs the value
• click on colors (e.g. rgb(255, 0, 0)) in the code editor to pop up a color wheel
• The second (blue) ☰ button generates a data URL which can be used to save and share the current vector field. Note that the URL itself contains the full state of the application, including the GLSL code, all the UI settings, and the camera and initial conditions box. So this link can be used to share the exact state of the application with anyone else (e.g. on Twitter).
• AWSD keys to fly
• C key to frame camera on the initial conditions box
• P key to capture a screenshot of the current render in a new browser window
• H key to hide/show the sidebar UI
• F11 key to enter/exit fullscreen mode

Integration parameters

• gridSpace: the spacing between start points within the initial conditions box, relative to the box maximum extents
• tubeWidth: the radius of the rendered solution tubes, relative to the box maximum extents
• integrationTime: the total time to integrate over
• maxTimeSteps: the number of timesteps into which the integrationTime is broken into
• xmin: (etc.) initial conditions box bounds
• clipToBounds: renders only the portion of the solution curves which lies within the initial conditions box
• integrateForward: if selected, integrate over positive times i.e. the time interval [0, integrationTime], otherwise integrate over the time interval [-integrationTime/2, integrationTime/2]
• enableBounds: if disabled, the initial conditions box is locked (allowing the camera to be moved within the box)

Rendering parameters

• showBounds: whether to show the initial conditions box bounds
• exposure: controls overall brightness of image
• gamma: controls gamma correction factor of image
• contrast: controls image contrast
• saturation: controls image saturation
• fov: change the camera field-of-view
• hairShader: use a simple hair shading model for the specular component (otherwise uses the Blinn-Phong model)
• specShine: controls size of tube specular highlight
• specColor: the color of the specular highlight (blended with the diffuse tube color defined in the code)
• depthTest: controls whether tubes are opaque or blended

Advanced parameters

• rayBatch: the number of ray segments to render in one iteration (higher means convergence in less iterations, but slower iterations)
• maxIterations: the max iteration count, beyond which the render terminates. Increase this to improve the final image quality.
• subtractiveColor: treat the colors as absorption coefficients
• bgColor: change color of background (probably use in conjunction with subtractiveColor)
• light1_color: the color of the first light, used to modulate the diffuse reflectance from the tubes
• light2_color: the color of the second light, used to modulate the diffuse reflectance from the tubes
• light1_dir: the direction of the first light, used to modulate the diffuse reflectance from the tubes
• light2_dir: the direction of the second light, used to modulate the diffuse reflectance from the tubes
• dashes: enable animated dashes showing the direction of flow (must use in conjunction with depthTest)
• dash_spacing: space between animated dashes, relative to gridSpace
• dash_size: fractional size of dash, in [0, 1]
• dash_speed: rate of dash motion, in dashes per second
• RECORD: start/stop recording a GIF of the viewport interaction
• RECORD PERIOD: record a GIF of one dash period (for repeating GIFs of the animated dash motion)
• record_realtime: whether to record the real-time interaction to the GIF, or at the maximum frame-rate
• RENDER ANIM: start recording a GIF of a number of automatically rendered animated frames (the number specified via anim_frames). Each frame renders for the number of iterations specified via maxIterations. The camera can optionally (via anim_enable_turntable) be moved in a turntable motion through a specified number of degrees anim_turntable_degrees during the animation. The uniform float variable animFraction is available in the shader, which equals the number of elapsed frames divided by the total number of frames. At the end of the animation, a GIF is rendered (which may take some time) and saved to the downloads folder with a standard name.
• CANCEL ANIM: cancel the current animation recording
• anim_frames: how many animation frames to render in the generated GIF
• anim_enable_turntable: whether to move the camera in a turntable sweep motion during the animation
• anim_turntable_degrees: if turntable is enabled, how many degrees to rotate through