BarnDoorLightFilter

Overview


The BarnDoorLightFilter functions like a barn door in stage lighting. Typically there are four flaps attached to a light that shape the lighting by restricting where the light can shine.

Example of a Barn Door (in black) attached to a stage light.

If the flaps were stitched to each other, the ends of the flaps would form a rectangular portal that constrains the light.

This light filter operates by simulating such a portal, called the flap opening, shown in gray below:

The flap opening can be moved, resized, rotated, rounded, colored, and blurred, with varying blur per side. Here is a rough overview of the various shaping parameters.

The edge expands outwards and there are controls to scale the size of each edge.

edge size and per-edge scaling animation

There are two modes of the Barn Door, analytical and physical.

  • In physical mode, the ray between the shading point and the light is checked to see if it passes through the Barn Door rectangular portal. Light rays masked by the portal are darkened.
  • In analytic mode, the calculation is the same but the end of the ray on the light is replaced by the singular position of the Barn Door (a single point).  It treats the light as a point light for filter shadowing.
analytical mode physical mode no filter

There are two projection types, perspective and orthographic. These are mainly useful for analytical mode, shown below.

perspective projection orthographic projection no filter

The modes affect the shape of the light beam. In physical mode, the projection type determines how big the flap opening is:

  • In the perspective projection type, the flap opening size scales with projector_focal_distance (roughly maintaining the same solid angle / cone size).
  • In the orthogonal projection type, the flap opening remains a fixed size. Apart from this, the projection type does not matter.

Attribute Reference

Properties attributes

color

Rgb
default: [ 1, 1, 1 ]

Color within the Barn Door lit region. For each color channel 0 is full shadow and 1 is no shadow.

density

Float
default: 1.0

Fades the filter effect. 0 means no effect (like having no filter), and 1 means full effect.

edge

Float
default: 0.0

The size of the transition zone from the rounded box to the outside, as a proportion of width (or height, whichever is smaller).

edge_scale_bottom

Float
default: 1.0

The scale factor for the bottom edge.

edge_scale_left

Float
default: 1.0

The scale factor for the left edge.

edge_scale_right

Float
default: 1.0

The scale factor for the right edge.

edge_scale_top

Float
default: 1.0

The scale factor for the top edge.

invert

Bool
default: False

Swap application of the filter from inside the Barn Door to outside.

mode

Int enum
  0 = “analytical” (default)
  1 = “physical”

Analytical mode allows light to shading points that project to the flap opening. Physical mode allows light whose direction goes through the flap opening.

node_xform

Mat4d blurrable
default: [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ], [ 0, 0, 0, 1 ] ]

The transform of the filter.

pre_barn_distance

Float
default: 0.5

The distance from the BarnDoorLightFilter that the pre_barn_mode control takes effect.

See Also

Note: The distance from the BarnDoorLightFilter to the ground is 9.

pre_barn_mode

Int enum
  0 = “black”
  1 = “white”
  2 = “default” (default)

Force the region before the pre_barn_distance to be fully filtered (black), not filtered at all (white), or treated the same as elsewhere (default).

See Also

Note: Here pre_barn_distance is set to the distance from the BarnDoorLightFilter to the ground plane, just like the focal distance.

projector_focal_distance

Float
default: 30.0

The distance of the flap opening from the projector origin. Ignored for orthographic projection.

projector_height

Float
default: 1.0

The height of the frustum at distance 1.0.

projector_type

Int enum
  0 = “perspective” (default)
  1 = “orthographic”

The projection type used to map points to the flap opening. Perspective has a focal point, while orthographic does not.

projector_width

Float
default: 1.0

The width of the frustum at distance 1.0.

radius

Float
default: 0.0

The radius by which to convert the base box shape into a rounded box, as a proportion of half the width (or height, whichever is smaller).

rotation

Float
default: 0.0

The angle to rotate the Barn Door counter-clockwise as seen from the light, in degrees.

size_bottom

Float
default: 0.0

Additional size on the bottom edge.

size_left

Float
default: 0.0

Additional size on the left edge.

size_right

Float
default: 0.0

Additional size on the right edge.

size_top

Float
default: 0.0

Additional size on the top edge.

use_light_xform

Bool
default: True

Attach the filter to the light (in the -Z direction) and ignore node_xform.

General attributes

on

Bool
default: True

Turns the light filter on/off.


Examples


No light filter With BarnDoorLightFilter
filter = BarnDoorLightFilter("/Scene/lighting/barndoor") {
    ["node_xform"] = Mat4(-0.0291956, 0, 0.999573, 0, 
                           0.999573, 0, 0.0291956, 0, 
                           0, 1, 0, 0, 
                           0, 9, -7, 1),
    ["projector_width"] = 0.5,
    ["projector_height"] = 0.5,
    ["projector_type"] = "perspective",
    ["projector_focal_distance"] = 9,
    ["pre_barn_mode"] = "black",
    ["pre_barn_distance"] = 0,
    ["mode"] = "physical",
    ["invert"] = false,
    ["radius"] = 0.2,
    ["edge"] = 0.2,
    ["use_light_xform"] = true,
    ["edge_scale_top"] = 1.0,
    ["edge_scale_bottom"] = 0.11,
    ["edge_scale_left"] = 0.5,
    ["edge_scale_right"] = 10,
    ["rotation"] = 35,
    ["density"] = 0.95,
    ["color"] = Rgb(1,1,1),
    ["on"] = true,
    ["size_top"] = 0,
    ["size_bottom"] = 0,
    ["size_left"] = 0,
    ["size_right"] = 0,
}

In the following examples, a BarnDoorLightFilter is above the scene aiming straight down from a light. The focal length is such that the flap opening occurs exactly at the ground plane. The scene geometry is designed to illustrate the shape of the rectangular flap opening and the shape of the filtered light.

on

on=true on=false