Projections

This section describes the projections (pixel mappings) availables.

Note

Only the Cartesian projection is available in the GUI. To use other projections, export a script from the GUI (once coloring options are selected…) and modify the projection parameter in batch mode:

batch_params = {"projection": projection}

class fractalshades.projection.Projection

A Projection defines a mapping acting on the screen-pixels before iteration. It implements the associated modifications of the derivatives, when needed (for distance estimation or shading).

For a xy_ratio - zoom parameter - equal to 1, screen pixels are defined in \([0.5, 0.5] \times [-0.5, 0.5]\)

More generally, the screen is a rectangle and pixel coordinates take values in:

\[[0.5, 0.5] \times \left[ -\frac{0.5}{xy\_ratio}, \frac{0.5}{xy\_ratio} \right]\]

The projection is defined as:

\[(\bar{x}_{pix}, \bar{y}_{pix}) = f(x_{pix}, y_{pix})\]

or alternatively with complex notations:

\[\bar{z}_{pix} = f(z_{pix})\]

Derived classes shall implement the actual \(f\) function

__init__(*args, **kwargs)

class fractalshades.projection.Cartesian(expmap_seam=None)

__init__(expmap_seam=None)

A Cartesian projection. This is simply the identity function:

\[\bar{z}_{pix} = z_{pix}\]

This class can be used with arbitrary-precision deep zooms.

Parameters:

`expmap_seam`: None | float

If not None, will ensure a smooth transition between cartesian and exponential projections (by simulating the scaling a Expmap applies to the derivatives). The expmap_seam value shall usually be set at 1.0, if the Expmap projection dx is half of the Cartesian projection dx (ie, the reference diameter of the Expmap matches the reference width of the cartesian mapping). Otherwise, it is an additionnal scaling factor. Note: parameter only valid for arbitrary-precision implementations.

class fractalshades.projection.Expmap(hmin, hmax, rotates_df=True, orientation='horizontal')

__init__(hmin, hmax, rotates_df=True, orientation='horizontal')

An exponential projection will map \(z_{pix}\) as follows:

\[\bar{z}_{pix} = \exp(h_{moy}) \cdot \exp(dh \cdot z_{pix}) \]

where:

\[\begin{split}h_{moy} &= \frac{1}{2} \cdot (h_{min} + h_{max}) \\ dh &= h_{max} - h_{min}\end{split}\]

This class can be used with arbitrary-precision deep zooms.

Parameters:

hmin: str or float or mpmath.mpf

scaling at the lower end of the h-axis, hmin >= 0.

hmax: str or float or mpmath.mpf

scaling at the higher end of the h-axis, hmax > hmin

rotates_df: bool

If True (default), the derivative will be scaled but also rotated according to the mapping. If False, only the scaling will be taken into account. A rule of thumb is this value shall be set to True for a standalone picture, and to False if used as input for a movie making tool.

orientation: “horizontal” | “vertical”

The direction for the h axis. Defaults to “horizontal”.

Notes

Note

Adjustment of zoom parameters: The xy_ratio of the zoom will be adjusted (at runtime) to ensure that \(\bar{y}_{pix}\) extends from \(- \pi\) to \(\pi\). nx is interpreted as nh for all values of the direction parameter (“horizontal” or “vertical”).

Note

Large mappings and computation by steps: For large exponentional mappings which may cover several orders of magnitude, computation will be run by steps. Each step:

• reuses the same reference orbit

• updates the BLA table as needed by the scale

• updates the reference size used to avoid overflows in derivatives

class fractalshades.projection.Generic_mapping(f, df)

__init__(f, df)

This class allows the user to provide a custom mapping defined on the complex plane.

The transformation between the complex plane and local pixel coordinates (map \(z_{pix}\), according to the zoom level) is managed internally.

Known limitations:

• currently only differentiable mappings of the complex variable (aka holomorphic / meromorphic functions) are supported.

• not suitable for arbitray precision fractals.

Parameters:

f: numba jitted function numba.complex128 -> numba.complex128

The complex function defining the mapping. If a tuple (f1, f2) or (f1, f2, f3) is provided the composition will be applied (f1 o f2)

df: numba jitted function numba.complex128 -> numba.complex128

The differential of f. If a tuple (df1, df2) or (df1, df2, df3) is provided the differential of the composition will be applied according to the differentiation chain rule.