Emitters

Emitters are a special type of controller that create new particles in a group. They can be configured to emit particles at a specific rate, or can be used to emit a burst of particles at will.

As factories for particles, emitters have several features for specifying the initial particle parameters. A template particle is provided as a basis for the particles emitted. Specified alone, each particle emitted is an exact clone of this template. The basic template may be augmented by a deviation template, which specifies the statisical deviation of the Particle attributes. This allows you to easily express how much, and in what way each particle differs from one another.

class lepton.Particle(**kwargs)

A template for particle creation. Parameters are specified as keyword arguments to the constructor:

position

The position of the particle, as a 3-item tuple.

velocity

The velocity of the particle, as a 3-item tuple.

size

The size of the particle, as a 3-item tuple.

up

The current orientation of the particle, as a 3-item tuple of euler angles.

If using the Billboard renderer, only the z component is in fact relevant; the other components are discarded.

The other renderers do not support rotation.

rotation

The rotation of the particle, as a 3-item tuple of euler angular velocities.

color

The color of the particle, as a 4-item tuple.

mass

The mass of the particle as a float.

age

The age of the particle as a float.

Particle attribute values may also be expressed as a sequence of discrete values (e.g., the colors of the rainbow, discrete sizes, etc). This is done by passing a list of values as a keyword argument to the emitter, for example:

emitter = StaticEmitter(
    ...
    position=[(0, 0, 0), (100, 0, 0), (200, 0, 0)]
)

Particle attribute values may also be generated randomly within a Domain:

jet = StaticEmitter(
    rate=2000,
    position=domain.Disc(
        (0, 0, -50),  # center
        (0, 0, 1),  # normal
        1.5,  # inner radius
        1.5  # outer radius
    ),
)

This flexibility allows powerful control over the desired range of composite attributes, such as position, velocity and color vectors.

Two emitters are currently included with lepton:

• StaticEmitter – Emits particles at a regular rate over time, or can emit an arbitrary number at once
• PerParticleEmitter – Emits particles originating from the positions of all existing particles in a group. Useful for creating trails of particles, like, for example, fireworks.

class lepton.emitter.StaticEmitter

Creates particles in a group at a fixed rate deriving particle attributes from a configurable mix of domain, discrete value lists and fixed template particles plus random deviation

StaticEmitter(rate, template=None, deviation=None, time_to_live=None, **discrete)

rate – Emission rate in particles per unit time.

template – A Particle instance used as the basis (mathematical average) for the emitted particles’ attributes for attributes not specified using a keyword argument

deviation – A Particle instance used as the standard deviation for randomizing the particle attributes. If deviation is not specified then the emitted particles attribute values are deterministic

time_to_live – If specified, the emitter will unbind itself from its calling group after the specified time has elapsed. This allows you to schedule the emitter to stop participating in a group after a certain elapsed time.

discrete – Additional keyword arguments can be supplied to specify discrete values for particular particle attributes. These values override the cooresponding value in the template. The values may be supplied as a sequence of specific values, or as a domain instance (or any object with a generate() method returning values). This allows you to specify a discrete range of values that will be used uniformly for a particular attribute. Note the discrete values are still randomized by the deviation template the same way as the template values.

emit(count, group) → None

Emit count new particles into the group specified. This call is not affected by the emitter rate or time to live values.

rate

Rate of particle emission per unit time

time_to_live

Time remaining before emitter is removed from the group (-1 to disable)

class lepton.emitter.PerParticleEmitter

Creates particles in a group for each particle in a source group at a fixed rate. Particle attributes are derived from a configurable mix of source particle, domain, discrete value lists and fixed template particles plus random deviation

PerParticleEmitter(source_group, rate, template=None, deviation=None,

time_to_live=None, **discrete)

source_group – Source particles used as templates for new particles rate – Emission rate in particles per unit time.

template – A Particle instance used as the basis (mathematical average) for the emitted particles’ attributes for attributes not specified using a keyword argument

deviation – A Particle instance used as the standard deviation for randomizing the particle attributes. If deviation is not specified then the emitted particles attribute values are deterministic

time_to_live – If specified, the emitter will unbind itself from its calling group after the specified time has elapsed. This allows you to schedule the emitter to stop participating in a group after a certain elapsed time.

discrete – Additional keyword arguments can be supplied to specify discrete values for particular particle attributes. These values override the cooresponding value in the template. The values may be supplied as a sequence of specific values, or as a domain instance (or any object with a generate() method returning values). This allows you to specify a discrete range of values that will be used uniformly for a particular attribute. Note the discrete values are still randomized by the deviation template the same way as the template values.

emit(count, group) → None

Emit count new particles per source particle into the group specified. This call is not affected by the emitter rate or time to live values.

rate

Number of particles per particle in the source group emitted per unit time

source_group

Source particle group containing template particles

time_to_live

Time remaining before emitter is removed from the group (-1 to disable)