Core components

This section describes the core components of the application.

class fractalshades.Fractal(directory: str)

__init__(directory: str)

The base class for all escape-time fractals calculations.

Derived class should implement the actual calculation methods used in the innner loop. This class provides the outer looping (calculation is run on successive tiles), enables multiprocessing, and manage raw-result storing and retrieving.

Parameters:

directorystr

Path for the working base directory

Notes

These notes describe implementation details and should be useful mostly to advanced users when subclassing.

Note

Special methods

this class and its subclasses may define several methods decorated with specific tags:

fractalshades.zoom_options

decorates the method used to define the zooming

fractalshades.calc_options

decorates the methods defining the calculation inner-loop

fractalshades.interactive_options

decorates the methods that can be called interactively from the GUI (right-click then context menu selection). The coordinates of the click are passed to the called method.

Note

Saved data

The calculation raw results (raw output of the inner loop at exit) are saved to disk and internally accessed during plotting phase through memory-mapping. They are however not saved for a final render. These arrays are:

subset

boolean Saved to disk as calc_name_Z.arr in data folder

Z

Complex fields, several fields can be defined and accessed through a field string identifier. Saved to disk as calc_name_Z.arr in data folder

U

Integer fields, several fields can be defined and accessed through a field string identifier. Saved to disk as calc_name_U.arr in data folder

stop_reason

Byte codes: the reasons for loop exit (max iteration reached ? overflow ? other ?) Saved to disk as calc_name_stop_reason.arr in data folder

stop_iter

Integer: iterations count at loop exit Saved to disk as calc_name_stop_iter.arr in data folder

The string identifiers are stored in codes attributes.

clean_up(calc_name=None)

Deletes all saved data files associated with a given calc_name.

Parameters:

calc_namestr | None

The string identifying the calculation run for which we want to delete the files. If None, delete all calculation files

zoom(*, x: float = 0.0, y: float = 0.0, dx: float = 8.0, nx: int = 800, xy_ratio: float = 1.0, theta_deg: float = 0.0, projection: ~fractalshades.projection.Projection = <fractalshades.projection.Cartesian object>, has_skew: bool = False, skew_00: float = 1.0, skew_01: float = 0.0, skew_10: float = 0.0, skew_11: float = 1.0)

Define and stores as class-attributes the zoom parameters for the next calculation.

Parameters:

xfloat

x-coordinate of the central point

yfloat

y-coordinate of the central point

dxfloat

span of the view rectangle along the x-axis

nxint

number of pixels of the image along the x-axis

xy_ratio: float

ratio of dx / dy and nx / ny

theta_degfloat

Pre-rotation of the calculation domain, in degree

projectionfractalshades.projection.Projection

Kind of projection used (default to fractalshades.projection.Cartesian)

has_skewbool

If True, unskew the view base on skew coefficients skew_ij

skew_ijfloat

Components of the local skw matrix, ij = 00, 01, 10, 11

class fractalshades.PerturbationFractal(directory)

__init__(directory)

Base class for escape-time fractals implementing the perturbation technique, with an iteration matching:

\[\begin{split}z_0 &= 0 \\ z_{n+1} &= f ( z_{n} ) + c\end{split}\]

Where \(f\) has a critical point at 0. Derived classes should provide the implementation for the actual function \(f\).

Parameters:

directorystr

Path for the working base directory

zoom(*, precision: int, x: ~mpmath.ctx_mp_python.mpf, y: ~mpmath.ctx_mp_python.mpf, dx: ~mpmath.ctx_mp_python.mpf, nx: int, xy_ratio: float, theta_deg: float, projection: ~fractalshades.projection.Projection = <fractalshades.projection.Cartesian object>, has_skew: bool = False, skew_00: float = 1.0, skew_01: float = 0.0, skew_10: float = 0.0, skew_11: float = 1.0)

Define the zoom parameters for the next calculation.

Parameters:

precisionint

number of significant base-10 digits to use for full precision calculations.

xstr or mpmath.mpf

x-coordinate of the central point

ystr or mpmath.mpf

y-coordinate of the central point

dxstr or mpmath.mpf

span of the view rectangle along the x-axis

nxint

number of pixels of the image along the x-axis

xy_ratio: float

ratio of dx / dy and nx / ny

theta_degfloat

Pre-rotation of the calculation domain, in degree

projectionfractalshades.projection.Projection

Kind of projection used (default to fractalshades.projection.Cartesian)

has_skewbool

If True, unskew the view base on skew coefficients skew_ij

skew_ijfloat

Components of the local skew matrix, with ij = 00, 01, 10, 11

class fractalshades.Fractal_plotter(postproc_batch, final_render: bool = False, supersampling: ~typing.Literal[<enum 'SUPERSAMPLING_ENUM'>] = 'None', jitter: bool = False, recovery_mode: bool = False)

__init__(postproc_batch, final_render: bool = False, supersampling: ~typing.Literal[<enum 'SUPERSAMPLING_ENUM'>] = 'None', jitter: bool = False, recovery_mode: bool = False)

The base plotting class.

A Fractal plotter is a container for fractalshades.postproc.Postproc_batch and fractal layers.

Parameters:

postproc_batch

A single fractalshades.postproc.Postproc_batch or a list of theses. They shall to the same unique Fractal object.

final_renderbool

• If False, this is an exploration rendering, the raw arrays will be stored to allow fast modification of the plotting options for an already computed zoom - without recomputing. High-quality rendering (supersampling, jitter) is disabled in this case.

• If True, this is the final rendering, the image tiles will be directly computed by chunks on the fly to limit disk usage, and stored in a memory-mapped array (.postdb extension). High quality rendering options are available only in this case (antialising, jitter). Raw arrays are not stored in this case, any change made to the plotting parametrers will need a new calculation. However an interrupted calculation might still be restarted, see parameter recovery_mode.

supersamplingNone | “2x2” | “3x3” | … | “7x7”

Used only for the final render. if not None, the final image will leverage supersampling (from 4 to 49 pixels computed for 1 pixel in the saved image)

jitterbool | float

Used only for the final render. If not None, the final image will leverage jitter, default intensity is 1. This can help reduce moiré effect

recovery_modebool

Used only for the final render. If True, will attempt to reload the image tiles already computed. Allows to restart an interrupted calculation in final render mode (this will result in a ‘patchwork’ if plotting parameters have been modified).

Notes

Warning

When passed a list of fractalshades.postproc.Postproc_batch objects, each postprocessing batch shall point to the same unique Fractal object.

add_layer(layer)

Adds a layer field to allow subsequent graphical operations or outputs.

Parameters:

layerfractalshades.colors.layers.Virtual_layer or a derived class

The layer to add

Notes

Warning

Layer postname shall have been already registered in one of the plotter batches (see method fractalshades.postproc.Postproc_batch.add_postproc).

Warning

When a layer is added, a link layer -> Fractal_plotter is created ; a layer can therefore only be added to a single Fractal_plotter.

plot()

The base method to produce images.

When called, it will got through all the instance-registered layers and plot each layer for which the output attribute is set to True.

save_db(relpath=None, postdb_layer=None, recovery_mode=False)

Saves the post-processed data in a numpy structured memmap.

Goes through all the registered layers and stores the results in a (nposts, ny, nx) memory mapping - with PIL-compliant coordinate indexing order. In case of supersampling all data points are stored (Downsampling filtering is delayed to the coloring stage), unless the postdb option is activated. A companion text file <relpath>.info is also written: it provides a short description of the data structure.

Parameters:

relpathOptional, str

path relative to self.fractal.directory. If not provided, defaults to either:

• "layers.db" (when parameter`postdb_layer` is not provided, and all layers are saved as float)

• f"{postdb_layer}.postdb" (when parameter postdb_layer is provided, and this layer is saved as rgb)

postdb_layerOptional, str

If provided, instead of saving all the layers, saves the layer with this name as a rgb array (ny, nx, nchannels) memory mapping, with extension *.postdb. This offers less flexibility (post processing is ‘frozen’) but optimises performances & disk use - esp. in case of supersampling as L2 downsampling filter can be applied before storing the image data.

recovery_modebool

If True, will attempt to reload the .db / .postdb tiles already computed. Allows to restart an interrupted calculation (this will result in a ‘patchwork’ if plotting parameters have been modified).

Notes

The file extension is either :

• .db (denoting the float values of fields are saved)

• .postdb (denoting the rgb arrays are saved)

@fractalshades.zoom_options

Decorates the method used to define the zooming (only one per fractalshades.Fractal class). The last kwargs passed to the zoom method can be retreived as fractal.zoom_kwargs

@fractalshades.calc_options

Decorates the calculation methods (there can be several such methods per fractalshades.Fractal class) The list of such calculation methods can be retrieved as fs.utils.calc_options.methods(f.__class__) After each call, the calling kwargs and results are forwarded to the Fractal instance method calc_hook for further processing

@fractalshades.interactive_options

Decorates the methods that can be called interactively from the GUI (There can be several such methods for a fractalshades.Fractal class) The list of these methods can be retreived with: fs.utils.interactive_options.methods(f.__class__)