SurfaceExplorer Files

Which file do I need?

• macOS 12.0+ (Universal) — SurfaceExplorer-v1.3-macos.dmg
• Windows 10/11, 64-bit — SurfaceExplorer-1.3-windows-x64.zip
• Linux, any x86_64 distribution — SurfaceExplorer-v1.3-linux-x86_64.AppImage
• Linux, optional — install-linux.sh, adds the AppImage to your applications menu

An iOS build is available on the App Store.

macOS

Open the .dmg and drag the app to your Applications folder. It is signed with an Apple Developer ID and notarized, so it opens normally on first launch — no Gatekeeper workaround needed.

Windows

Extract the zip into a folder of its own and run SurfaceExplorer.exe. The archive has no top-level folder: it holds the executable together with the Qt libraries and the plugin folders it loads at startup, so they all have to stay side by side.

The build is not code-signed, so Windows shows a “Windows protected your PC” notice the first time you run it. Choose More info, then Run anyway.

Linux

Download both SurfaceExplorer-v1.3-linux-x86_64.AppImage and install-linux.sh into the same folder, then run:

:::bash
bash install-linux.sh

It copies the AppImage to ~/Applications, makes it executable and adds it to your applications menu with its icon, so from then on you launch it like any other app. Re-run it to update, bash install-linux.sh --uninstall to remove. No root needed.

To run the AppImage directly instead, make it executable first. A downloaded file carries no permissions, and without this your desktop may hand it to a disk-image tool instead of launching it:

:::bash
chmod +x SurfaceExplorer-v1.3-linux-x86_64.AppImage
./SurfaceExplorer-v1.3-linux-x86_64.AppImage

Requirements

• GPU with Vulkan 1.0+, Metal, Direct3D 11+ or OpenGL 3.3+
• Built with Qt 6.10.2

Known issues

Windows / Direct3D. Presets that drive the Geodesic Flow solver from a metric written in the Equations panel may fail to render correctly on the Direct3D backend: the application can stop responding and be closed by the system. They work as expected on the other platforms.

Source and bug reports

• Source code — github.com/dioscorid-design/SurfaceExplorer
• Bug reports — github.com/dioscorid-design/SurfaceExplorer/issues

What's new since v1.2

• Cross Section: 3D slices of 4D surfaces: the Implicit tab is now split in two. 3D is the ray marching you already know; Cross Section takes an equation in four variables — x, y, z and p — and draws the 3D slice the camera sees. The default surface is a genuine 3-torus: at p = 0 it does not collapse into the ordinary 2D torus, it is the real section of the 4D object.

• The 4D rotations now choose which slice you see: turning the surface in 4D changes where the plane cuts it, the way tilting a torus changes the section a fixed plane produces. The Omega/Phi/Psi buttons work in both the 3D and 4D docks, and the P+/P- buttons slide the cutting plane along the fourth coordinate, so you can travel through the object instead of always seeing its middle slice.

• The 4D camera path works in Cross Section too: the path moves the camera through 4D space and the slice follows it, so a recorded flight shows the object changing shape as you go. Path equations stay disabled in the 3D sub-tab, where they would have no effect.

• Shell thickness is now a slider: the shell wall used to be a fixed value in the shader, and its real thickness depended on how the equation happened to be written — a surface scaled down by a factor in front of it got a much thicker wall than one written at natural scale. The thickness is now a true length you set yourself, in the Implicit tab under Shell/Solid, and it is saved with the preset. Existing shells may look thinner than before: the ones that relied on a scaled-down equation need the slider raised to get their old look back.

• Headlight: an extra light coming from the viewer, off by default. The two main lights sit almost opposite each other and leave a band of directions neither reaches: surfaces facing that way stay black however far you push Light Intensity, which multiplies. Most visible along a camera path, inside a tube or a cavity. Saved with the scene.

• Fast / Precise marcher: on equations of high degree the ray marcher could report a hit in empty space, showing up as a false weld joining parts that are actually separate, or a thick spur on the object. Precise finds the surface by where the equation changes sign, so it cannot hit empty space. Costs about 70% more on the surfaces that need it; Fast stays the default and is identical to previous versions. The choice is saved with the surface, and Cross Section surfaces open on Precise.

• Render controls grouped together: Shell/Solid, Fast/Precise and Shell Thickness now sit in one panel above the spatial limits, shared by both Implicit sub-tabs. Shell/Solid is a single pair instead of one per sub-tab.

• A guard against freezing the GPU: applying a relief texture to a transparent ray-marched surface could collapse rendering and lock the application, on desktop too, before the performance watchdog had anything to measure. The relief is computed at every step of every ray and transparency multiplies those steps. The scene is now set opaque and the motion stopped first, and you are asked whether to restore them.

• The 4D dock buttons now show how far you have moved: each pair of step buttons (X, Y, Z, P, Omega, Phi, Psi) has a figure beside it, counting only what you move with that button — a rotation or a camera path running at the same time leaves it alone. It starts at zero on every surface, and loading a preset makes that preset the new reference. Without it there was no way to tell how far a few clicks had taken you, or to get back to a known position.

• New background shapes: Sphere, Cylinder, Cube: the background can now follow the camera as a sky around the scene, in addition to staying fixed on screen.

Main fixes

• Ray marching surfaces and records save their full state: an equation written in Cross Section was saved as the one from the 3D sub-tab, so reopening it showed the default sphere. The 4D rotations were being zeroed on purpose — a leftover from when ray marching ignored them — and the position of the cutting plane was not saved at all. Surfaces and records are two separate paths and both were affected.

• Constants no longer reset to 1 on load: a surface reopened with its constants wiped and its shape deformed. The check that decides which constants are in use was reading the sub-tab that was on screen before the preset had been applied.

• Other ray marching surfaces are no longer broken after visiting Cross Section: the engine kept using the 4D equation for every surface loaded afterwards, and only restarting the app cleared it.

• Switching sub-tab leaves a clean scene: motion, camera paths, sound, surface and background textures and the loaded script survived the change and kept running on the default surface that had just replaced them.

• Default surfaces no longer inherit the previous lighting: arriving in Ray Marching from a surface set to Phong, the default sphere and the 3-torus came up in Phong as well.

• Texture scripts had lost p, the 3D point: freeing the name for the fourth coordinate broke every ray marching script that used it, with no error shown — the surface simply disappeared.

• Headlight is reset and saved like the other controls: it kept the value of the previous scene when you loaded a new surface, and it was never written to the preset.

• Saving from Cross Section recorded the Shell/Solid state of the 3D sub-tab: the two sub-tabs had separate radio buttons for a setting that has always been a single one.

• Shell Thickness now greys out in Solid, where there is no shell wall to set; Ray Steps and Step Relax grey out with the Precise marcher, where they have no effect on what you see.

• Time restarts from zero on the default ray marching surface: reloading it and putting t back in the equation started the surface at the time elapsed since the app was launched, not at zero. It was not frozen — a surface evolving as 1/sqrt(t) at large t simply changes too slowly to see.

• Enter restarts the clock after a Stop: committing an equation with Enter applied it but left the geometry clock off, so it took an explicit Run to get moving again.

• Equations that do not describe a surface are now refused: 1 = 0 was accepted in silence, leaving an empty screen and no error; so were x = 0 and x^2 = 1, infinite planes the marcher draws as flat backdrops. An equation must now use at least two of x, y and z — two, not three, so a cylinder like x^2 + y^2 = 1 still works. Clearing the field and pressing Enter says so instead of silently leaving the previous surface on screen.

• Clearing the equation no longer deforms the surface: the constants were reset to 1 as soon as the field went empty, and the Cross Section default — which needs A > B > C — collapsed into a shape nobody asked for. An empty field now disables the constants without overwriting their values.

• NEW now fully clears the scene: the Cross Section equation, greyed-out Render controls, and leftover A–F/S constants from the previous surface all used to survive it.

• Moving the view of an empty scene no longer counts as work: after NEW, a single drag of the mouse over the empty view was enough to have the app ask whether to save it, the next time you loaded something or closed the window.

• NEW resets Shell/Solid and Fast/Precise: they kept the setting of the last preset loaded.

• Sliders greyed out by Precise now say why: hovering Ray Steps or Step Relax explains that the precise marcher makes them inert.

• Enter starts a camera path: writing a path equation and pressing Enter now sets it going, instead of only taking effect the next time you pressed Departure. With the path already running, Enter still applies your edits on the fly; clearing all the fields and pressing Enter stops it and returns the buttons to Departure and Start.

• A camera path can be written with a single coordinate: Departure stayed off until two fields were filled, refusing perfectly good paths that run along one axis — the others are simply zero. Angles and roll do not count towards this: on their own they leave the camera standing at the origin looking at itself, which showed up as the surface vanishing.

• The 4D dock figures no longer report motion you did not make: with a 4D rotation running, pressing any step button also made the Omega, Phi or Psi figure jump, reporting rotation the button had not produced.

• Departure no longer switches itself on in Cross Section: arriving from the Parametric tab lit the button even with no path written.

• Sync Focused Texture works on parametric surfaces too: the editor showed the updated code while the surface kept drawing the old one.

• A texture that gained a slider arrives with the slider live: it came in switched off and inert, which is the very case the command is for.

• Constants used only by the texture survive loading a record: on the first load they were reset to 1, so the same file rendered differently depending on what was on screen before.

• Editing a texture no longer breaks its link to the library: after a manual edit the record was saved without it, and Sync stayed greyed out for good.

• Clicking the texture already on screen restores its colours: it reset the clock and the 2D framing but left the colours alone.

• The library highlights the texture the record actually points to: between two presets sharing the same colour code it highlighted the wrong one, so clicking it loaded a different texture.

• Headlight tooltip is now one line, and says it has no effect on parametric surfaces.

• Sync Focused Texture now covers the background too: it used to update only the surface texture, leaving a background left behind by a library change with no way back — and no highlight in the Library tree either.

• A background texture keeps its own hint: loading one from the Library, or bringing it up to date with Sync, showed no message even when its sliders had one.