🔧 Parameters

This page focus on all shader-related parameters, and how they affect the final image (in practical terms). The main goal is for helping you to understand how to work with the software and parametrize it to your needs, create your own animations, and more.

• For rendering and exporting parameters, see the ShaderFlow page ✨
• For understanding the math, see the Foundations page 📜

All parameters are controlled within the state dictionary class, acessible by:

1
2
3
4
5

from DepthFlow import DepthScene

scene = DepthScene()
scene.state.height = 0.3
scene.state.offset_x = 1

Or settable by the command line as a animation component:

1
2

# Note: This will only create a static image
depthflow config --height 0.3 --offset-x 1 main

However, they are best used within the .update() method for creating animations:

1
2
3
4
5

import math

class YourScene(DepthScene):
    def update(self):
        self.state.offset_x = 0.3 * math.sin(self.cycle)

Internally, they are used and sent when the render method is called for the shader, which non-surprisingly happens in the main event loop of the Scene, after all .update()'s.

Directly controlling those makes more sense when managing the code within Python (and bypassing the animation system, which essentially does the same thing) for writing custom animations and more advanced interactions or behaviors.

Parallax¶

This section is about the core parameters of DepthFlow.

• Important: When parameters refers to depth values, the value is normalized. A steady value of \(0.5\), with a height of \(0.3\) means the perceptual steady values is at \(0.15\), (e.g.).

• Important: Depth values of zero are the farthest point, and values of one the closest.

• Note: The suggested ranges aren't enforced, but what makes sense in most cases.

Height¶

Type: float, Names: height, Range: [0, 1]

The height parameter defines the peak height of the projected surface at depth=1. It can be thought as the effect's global intensity parameter.

• A value of 0 means the surface is flat, while a value of 1 means the surface's peak is on the same \(xy\) screen plane as the camera.

• Notice how in the video, the center doesn't touch the camera, as its depth value isn't \(1\), but the closer bottom edge "gets below" the camera's view.

Offset¶

Type: Tuple[float, float], Names: offset_x, offset_y, Range: [-2, 2]

The offset parameter defines the parallax displacement of the projected surface. It can be thought as the camera's position parameter.

• A value of 0 in a component means the surface and camera are centered, other values meaning depends on other parameters and the aspect ratio, it's a bit experimental.

• This parameter isn't a "camera displacement" you might expect:

  1. That would simply move the image around without changing the perspective, which is what the center parameter does.
  2. The camera always "looks" to the image (origin parameter) by adding an opposite bias to the ray's projection on how much the image is displaced.

As you might expect, setting \(x=cos(t)\) and \(y=sin(t)\) parameter to follow a circular motion, will create a "orbiting" effect around the center of the image.

Steady¶

Type: float, Names: steady, Range: [-1, 1]

The steady parameter defines the depth at which no offsets happen. It can be thought as the offsets focal depth parameter.

• Notice how in the video, the orange line doesn't move when the offset changes, and the mirroring of relative directions when crossing this boundary.

• This parameter makes the ray projections "pivot" around this depth value internally.

Isometric¶

Type: float, Names: isometric, Range: [0, 1]

The isometric parameter defines how much perspective is applied. It can be thought as the planification effect parameter.

• A value of 0 means full perspective projection, while a value of 1 means the image is projected as if it was isometric (all rays are parallel).

  1. This completely negates the height parameter at isometric=1

• This parameter makes effect more "flat" and "2D", in fact, a value of 1 turns offsets into a simple translation. A value of 0.5 is often recommended.

Notice how in the video below the offsets are "flattened", as if there was one layer per depth value and it was simply displaced in the \(xy\) plane. Consequently, more of the image is visible, as the peak values don't race towards the camera as much, at the cost of being flat.

Dolly¶

Type: float, Names: dolly, Range: [0, 10]

The dolly parameter defines the camera's distance from the image. It's basically the same as the isometric effect parameter, but with different (natural) units.

• As you move away to objects, they appear more isometric, that's the reason why your face looks unnatural in close-up selfies.
• A dolly value of 0 is the same as isometric=0
• A dolly value of \(\infty\) is the same as isometric=1

As far as I know, the convertion factor between the two is given by:

For the traditional 'dolly zoom' effect, combine it with the focus parameter.

Focus¶

Type: float, Names: focus, Range: [-1, 1]

The focus parameter defines the steady depth on isometric changes. It can be thought as the isometric focal depth parameter.

• Notice how in the video, the orange line doesn't move when the isometric changes, and the mirroring of perspective directions when crossing this boundary.

• This parameter makes this depth value the \(z=1\) plane internally.

Zoom¶

Type: float, Names: zoom, Range: (0, 1]

The zoom parameter defines the camera's field of view. It can be thought as the you-know-it parameter.

• A value of 1 means the image is fully visible, while a value of 0.5 means a quarter of the image is visible.

• This is a "digital zoom", it simply stretches the coordinates internally.

Invert¶

Type: float, Names: invert, Range: [0, 1]

The invert parameter interpolates between 0=far and 1=near and the opposite. It can be thought as the depth inversion parameter.

• A value of 0.5 flattens the depth map and nothing happens, while a value of 1 inverts the depth map. Middle values can be thought as softening the depthmap.

• It wraps the surface inside-out when the value is above 0.5, and a lot of encroaching will happen, as the background is now the foreground.

Center¶

Type: Tuple[float, float], Names: center_x, center_y, Range: ([-ar, ar], [-1, 1])

The center parameter defines the center of the image. It can be thought as the raw offset parameter.

• A value of 0 in a component means the image is centered, other values applies a direct offset to the contents of the image.

• This parameter is a "camera displacement" you might expect, nothing fancy.

Origin¶

Type: Tuple[float, float], Names: origin_x, origin_y, Range: ([-ar, ar], [-1, 1])

The origin parameter defines the center point of offsets. It can be thought as if the camera was above this point , without moving it.

• The value sets "the origin" of offsets to the projections of the image.

• It is also the value at which height changes only causes zooming

Depth of Field¶

Vignette¶