spacr.qt.widgets.fractal_space¶

Forward flight through a dark star field, with sparse celestial objects.

The third spaceout pattern, beside the orbit fold and the fold-inversion cascade. It is the quiet one: predominantly black, with a very low-amplitude broad hue field, six parallax star layers travelling toward the viewer, and three object slots that pass by – mostly stars, occasionally a lit planet or a bright sun with a halo.

WHY IT SUITS A BACKDROP better than the other two. The orbit fold and the cascade fill the frame with structure, which is what they are for and also what makes them compete with the interface in front of them. Space is mostly empty, so the thing a user is reading stays the brightest object on screen.

Both backends draw the same scene: the GLSL below and the Numba kernels in fractal_travel’s CPU path share the star-field and object maths, so a machine without a GPU sees the same flight rather than a different one.

Classes¶

SpaceEngine

The CPU side of the flight, driven exactly like the other engines.

Module Contents¶

class spacr.qt.widgets.fractal_space.SpaceEngine(thread_count: int)[source]¶

The CPU side of the flight, driven exactly like the other engines.

Parameters:: thread_count – worker threads numba may use.

samples is how many samples a side each pixel takes, set by the widget from the Supersampling setting. None – an engine nobody configured – keeps the old rule of two on a small frame and one on a large one.

The widget builds and calls every pattern engine the same way, so this takes the same arguments even where the scene has no use for one. A pattern that needed a different call would put a branch in the one place all three are meant to look alike.

Create the space renderer and cap numba’s thread pool to match.

Parameters:: thread_count – worker threads to render with; clamped to at least one. A numba that cannot be configured is tolerated – the renderer still works, it just shares the default pool.

render(width: int, height: int, t: float, speed: float, dream: float = 0.0, iterations: int = 0, pointer_x: float = 0.0, pointer_y: float = 0.0, pull: float = 0.0, push: float = 0.0) → numpy.ndarray[source]¶

One finished frame as (height, width, 3) uint8.

Parameters:

width – width of the finished frame in pixels.
height – height of the finished frame in pixels.
t – elapsed animation time used to advance the flight.
speed – multiplier applied to the flight’s forward motion.
dream – unused. The flight has no dream term – the scene is a star field, and warping it toward a hallucination is what the other two patterns are for.
iterations – unused. The cost here is six parallax layers and three object slots, all fixed, so there is no depth to trade.
pointer_x – where the pointer is, in scene coordinates.
pointer_y – as above.
pull – how strongly the pointer draws the flight toward it.
push – a click’s shove, decaying.

THE POINTER STEERS RATHER THAN WARPS. The other patterns bend their field toward the cursor; bending a star field would make the stars curve, which reads as a fault rather than as attention. Here it nudges the flight’s heading, so the field slides the way a camera pans and every star stays a point.

spacr.qt.widgets.fractal_space.render_space_frame(width: int, height: int, t: float, speed: float, offset_x: float, offset_y: float, samples: int) → numpy.ndarray¶

A whole frame of the flight.

nogil because this runs on the shading thread and the GUI thread has to keep answering while it does.

When Numba is unavailable, the public render_space_frame name instead accepts arbitrary positional and keyword arguments and raises RuntimeError.

Parameters:

width – frame width in pixels.
height – frame height in pixels.
t – elapsed animation time used to advance the flight.
speed – multiplier applied to the flight’s forward motion.
offset_x – horizontal shift added to every pixel’s scene coordinate, which steers the flight’s heading.
offset_y – vertical shift added likewise.
samples – 1 or less takes one sample at each pixel centre; anything larger averages a samples x samples grid of samples per pixel (it used to be 2 x 2 whatever the number said).

Returns:

(height, width, 3) uint8 RGB array.

Refuse: the CPU space renderer needs Numba, which is absent.

Parameters:

_args – whatever the caller would have rendered.
_kwargs – likewise.

Raises:

RuntimeError – always.

render_space_frame(*_args, **_kwargs) spacr/qt/widgets/fractal_space.py:664 spacr/qt/widgets/fractal_space.py:834

spacr.qt.widgets.fractal_space.sample_space(x: float, y: float, t: float, speed: float)¶

One pixel of the flight, in scene coordinates.

Kept a free function so a test can compare it with the shader and so the frame kernel below stays a loop and nothing else.

When Numba is unavailable, the public sample_space name instead accepts arbitrary positional and keyword arguments and raises RuntimeError.

Parameters:

x – horizontal scene coordinate; 0 is the frame centre and the shorter frame edge lies at about ±1.08.
y – vertical scene coordinate, positive upwards, on the same scale.
t – elapsed animation time used to advance the flight.
speed – multiplier applied to the flight’s forward motion.

Returns:

(red, green, blue), each clamped to [0, 1].

Refuse: the CPU space renderer needs Numba, which is absent.

Parameters:

_args – whatever the caller would have sampled.
_kwargs – likewise.

Raises:

RuntimeError – always.

sample_space(*_args, **_kwargs) spacr/qt/widgets/fractal_space.py:588 spacr/qt/widgets/fractal_space.py:825