Controllers

A controller is a callable of the form:

controller(timedelta, group)

Particle controllers are bound to particle groups and invoked via the group’s update() method. A typical controller will iterate all particles in a group, apply some logic and mutate the particles or remove or add particles to the group.

Lepton’s built-in controllers are written in C for performance, but Python functions or classes with __call__() methods can also be used.

Movement

Many of the controllers affect the position and velocity of particles.

class lepton.controller.Gravity

Imparts a fixed accelleration to all particles

Gravity((gx, gy, gz))

(gx, gy, gz) – Gravity vector

class lepton.controller.Movement

Updates particle position and velocity

Movement(damping=None, min_velocity=None, max_velocity=None)

damping – A three-tuple velocity multiplier per unit time in each respective dimension. A scalar may also be specified if the damping is equal in all dimensions (thus .25 is equivilent to (.25, .25. .25))

min_velocity – Minimum velocity scalar. Particle velocities less than this are scaled up, except for particles with no velocity since their velocity vectors have no direction

max_velocity – Maximum velocity scalar. Particle velocity magnitudes are clamped to this value

max_velocity

Maximum velocity magnitude, particle velocities magnitudes are clamped to this value.

min_velocity

Minimum particle velocity magnitude. All moving particles with velocities less than this minimum are sped up to min_velocity.

class lepton.controller.Bounce(domain, bounce=1.0, friction=0, bounce_limit=5, callback=None)

domain – Particles that collide with the surface of this domain are redirected as if they bounced or reflected off the surface. This alters the position and velocity of the particle. The domain must have a non-zero area.

bounce – The coefficient of restitution multiplied by the normal component of the collision velocity. This determines the deflection velocity of the particle. If 1.0 (default) the particle is deflected with the same energy it struck the domain with, if zero, the particle will stick to the domain’s surface and not bounce off.

friction – The resistance presented by the domain surface to sliding particle movement tangental to the domain. 1 - friction is multiplied by the tangental component of the particles velocity. A value of 0 means no friction. if friction is negative, the particle will gain velocity.

bounce_limit – The maximum number of bounces deflections calculated per particle per iteration. Higher values can result in more accuracy at potentially higher CPU cost. A value of -1 is effectively infinite.

callback – An optional function called when a particle collides with the domain. Must have the signature:

callback(particle, group, controller, collision_point, collision_normal)

collision_point is point on the domain where the collision occurred. collision_normal is the normal vector on the domain’s surface at the point of collision.

bounce

Multiplied by the normal component of the collision velocity, this determines the amount of deflection from the domain’s boundary. If positive, the particle will bounce off of the domain. If zero the particle will “stick” to the boundary. If negative, the particle will be refracted across the boundary

bounce_limit

The maximum number of bounces deflections calculated per particle per iteration. Important for fast moving particles contained inside small domains, or domains with corners. Small values may reduce CPU cost, but also may allow particles to escape containment.

callback

A function called called when a particle collides with the domain, or None Must have the signature:

callback(particle, group, controller, collision_point, collision_normal)

domain

Particles are deflected when they collide with the domain boundary

friction

Multiplied by the tangental component of the collision velocity, this determines the resistance to sliding tangentially across the domain boundary. 1 - friction is multiplied by the tangental component of the particle’s velocity.

class lepton.controller.Magnet(domain, charge, exponent=2, epsilon=0.00001, outer_cutoff=inf)

charge

Determines the magnitude of the magnetic force from the domain. A positive charge is attractive, a negative charge is repulsive.

domain

Particles are attracted or repulsed from the domain’s surface.

epsilon

As the distance between the particle and domain surface decreases the magnet’s force tends toward infinity. To improve stability, the value of epsilon is always added to the distance value when calculating the magnet force. The default value for epsilon is very close to zero, and provides a realistic simulation while avoiding infinite forces. Larger values may be desireable for certain visual effects where increased stability is more desirable than realistic physics. Using a value of zero for epsilon is not recommended to avoid infinite particle velocities.

exponent

The magnetic force falls off proportional to the particle distance from the domain raised to this power.

outer_cutoff

No force is exerted on particles with a distance from the domain greater than this value. Useful as an optimization to avoid calculating trivial forces on distant particles.

class lepton.controller.Drag

Simulate viscous drag in a fluid

Drag(c1, c2, fluid_velocity, domain)

c1 – Linear drag coefficient

c2 – Squared drag coefficient

fluid_velocity – Fluid velocity vector used to simulate a moving fluid

domain – If specified, only particles inside this domain are affected by the fluid drag.

c1

Linear particle drag coefficient

c2

Squared particle drag coefficient

domain

Only particles contained in this domain are affected by the controller

fluid_velocity

Fluid velocity vector

Color

These controllers affect the color or alpha (opacity) of particles.

class lepton.controller.Fader

Alters the alpha of particles to fade them in and out over time

start_alpha – Initial alpha value. fade_in_start – Time to start fading in to max_alpha fade_in_end – Time when alpha reaches max max_alpha – Maximum alpha level fade_out_start – Time to start fading out to end_alpha. If None no fade out is performed. fade_out_end – Time when alpha reaches end. end_alpha – Ending alpha level.

end_alpha

Ending particle alpha level.

fade_in_end

Time when alpha reaches max_alpha.

fade_in_start

Time to start fading in to max_alpha.

fade_out_end

Time when alpha reaches end_alpha

fade_out_start

Time to start fading out to end_alpha.

max_alpha

Max particle alpha value.

start_alpha

Initial particle alpha value.

class lepton.controller.ColorBlender

Changes particle color over time

ColorBlender(color_times, resolution=30)

color_times – A sequence of 2 or more (time, color) pairs where color is a 3 or 4 tuple of floats representing the color and time is the particle age when it is assigned that color. This list is used to create a gradient of colors for the particles over time. If a particle’s age is less than the smallest time or greater than the latest time, its color is not changed. Note that the time values can be specified in any order, but a particular time value should occur only once, a ValueError is raised if a time value is repeated

resolution – The number of colors per unit time in the cached gradient. A larger resolution will result in smoother color blending, but at the cost of memory and performance. A reasonable value is the expected frame rate of your application, or a lower value if the age span of color_times is especially long or if the color changes are not rapid. In general, pick the lowest value that gives acceptable visual results

resolution

The number of colors per unit time in the cached gradient.

Size

Particles may grow or shrink over time.

class lepton.controller.Growth

Changes the size of particles over time

Growth(growth, damping=1.0)

growth – Change in particle size per unit time. May be specified as a 3-tuple or scalar

damping – Growth multiplier to accelerate or decelerate growth over time. Also a 3-tuple or scalar.

Death

If you continue to emit particles into a group then the number of particles can grow in an unbounded way. To avoid this you should ensure there is some reliable way in which particles can be destroyed.

Particles may be destroyed after a certain per-particle lifetime, or perhaps when they move into or out of a domain.

class lepton.controller.Lifetime

Kills particles beyond an age threshold

Lifetime(max_age)

max_age – Age threshold, particles older than this are killed.

class lepton.controller.Collector

domain – particles inside or outside this domain are killed. The domain must have a non-zero volume.

collect_inside – True to collect particles inside the domain, False to collect particles outside the domain.

callback – an optional function called for each collected particle Must have the signature:

callback(particle, group, collector)

callback

A function called called for each collected particle, or None Must have the signature:

callback(particle, group, collector)

collect_inside

True to collect particles inside the domain, False to collect particles outside the domain.

collected_count

Total number of particles collected

domain

Particles inside or outside this domain are killed depending on the value of collect_inside