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 builtin 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 threetuple 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 nonzero 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 3tuple or scalar
damping – Growth multiplier to accelerate or decelerate growth over time. Also a 3tuple 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 perparticle 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 nonzero 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
