Spatial Domains

Domains provide a way to describe regions of space in Lepton. These regions can be used for things like collision detection or to constrain the initial values for attributes of new particles created via a ParticleEmitter.

Built-in domains

A number of built-in classes define common spatial domains.

class lepton.domain.Point(point)

Simple single point domain

closest_point_to(point)

Return the closest point in the domain to the given point and a normal vector at that point.

The point returned is always the domain point.

The normal returned for a point domain is a unit vector parallel to the line formed between the supplied point and the domain point, facing outward from the domain. This effectively treats the point domain like a zero-radius sphere.

generate()

Generate always returns the domain point

intersect(start_point, end_point)

You cannot intersect a point domain

class lepton.domain.AABox

Axis aligned rectangular prism

AABox(point1, point2)

point1 and point2 define any two opposite corners of the box

generate() → Vector

Return a random point inside the box

intersect(seg_start, seg_end) → point, normal

Intersect the line segment with the box return the first intersection point and normal vector pointing into space from the box side intersected.

If the line does not intersect, or lies completely in one side of the box return (None, None)

class lepton.domain.Cone

Right-cone domain with arbitrary orientation

Cone(apex, base, outer_radius, inner_radius=0)

apex – End point of cone axis at the apex where it tapers to zero radius. base – End point of cone axis at the base of the cone. outer_radius – The outer radius of the cone volume. inner_radius – The inner radius of the cone, must be <= outer_radius. Describes the radius of a smaller cone that is subtracted from the larger cone described by the outer_radius. defaults to 0, which creates a solid volume

apex

End point of cylinder axis

base

End point of cylinder axis

closest_point_to(point) → point, normal

Returns the closest point on the cone’s surface to the supplied point.

generate() → Vector

Return a random point in the cylinder volume

inner_radius

Inner radius of cone base. Set to zero for a solid volume

intersect(seg_start, seg_end) → point, normal

Intersect the line segment with the cylinder return the intersection point and normal vector pointing into space on the same side of the surface as the start point.

If the line does not intersect, or lies completely in the cylinder return (None, None)

length

Length of cylinder axis

outer_radius

Outer radius of cone base. Must be >= inner_radius

class lepton.domain.Cylinder

Capped right-cylinder domain with arbitrary orientation

Cylinder(end_point0, end_point1, outer_radius, inner_radius=0)

end_point0 – End point of cylinder axis end_point1 – End point of cylinder axis outer_radius – The outer radius of the cylinder volume. inner_radius – The inner radius of the cylinder, must be <= outer_radius. defaults to 0, which creates a solid volume

closest_point_to(point) → point, normal

Returns the closest point on the cylinder’s surface to the supplied point.

end_point0

End point of cylinder axis

end_point1

End point of cylinder axis

generate() → Vector

Return a random point in the cylinder volume

inner_radius

Inner radius of disc. Set to zero for a solid circle

intersect(seg_start, seg_end) → point, normal

Intersect the line segment with the cylinder return the intersection point and normal vector pointing into space on the same side of the surface as the start point.

If the line does not intersect, or lies completely in the cylinder return (None, None)

length

Length of cylinder axis

outer_radius

Outer radius of disc. Must be >= inner_radius

class lepton.domain.Disc

Circular disc domain with arbitrary orientation

Disc(center, normal, outer_radius, inner_radius=0)

center – The center point of the disc (3-number sequence) normal – Normal vector perpendicular to the disc. This need not be a unit vector. outer_radius – The outer radius of the disc. inner_radius – The inner radius of the disc, must be <= outer_radius. defaults to 0, which creates a solid circle

center

Center point of disc

closest_point_to(point) → point, normal

Returns the closest point on the disc’s surface to the supplied point.

generate() → Vector

Return a random point in the disc

inner_radius

Inner radius of disc. Set to zero for a solid circle

intersect(seg_start, seg_end) → point, normal

Intersect the line segment with the disc return the intersection point and normal vector pointing into space on the same side of the disc as the start point.

If the line does not intersect, or lies completely in the disc return (None, None)

normal

Normal vector that determines disc orientation

outer_radius

Outer radius of disc. Must be >= inner_radius

class lepton.domain.Line

line segment domain

Line(start_point, endpoint)

Define the line segment domain between the specified start and end points (as a sequence of 3 numbers)

closest_point_to(point) → point, normal

Returns the closest point and normal on the line to the supplied point.

generate() → Vector

Return a random point along the line segment domain

intersect(seg_start, seg_end) → point, normal

You cannot intersect a line segment

class lepton.domain.Plane

Infinite planar domain

Plane(point, normal, half_space=False)

point – Any point in the plane (3-number sequence) normal – Normal vector perpendicular to the plane. This need not be a unit vector. The half-space contained by the plane is opposite the direction of the normal.

closest_point_to(point) → point, normal

Returns the closest point and normal on the plane to the supplied point.

generate() → Vector

Aways return the provided point on the plane

intersect(seg_start, seg_end) → point, normal

Intersect the line segment with the plane return the intersection point and normal vector pointing into space on the same side of the plane as the start point.

If the line does not intersect, or lies completely in the plane return (None, None)

class lepton.domain.Point(point)

Simple single point domain

closest_point_to(point)

Return the closest point in the domain to the given point and a normal vector at that point.

The point returned is always the domain point.

The normal returned for a point domain is a unit vector parallel to the line formed between the supplied point and the domain point, facing outward from the domain. This effectively treats the point domain like a zero-radius sphere.

generate()

Generate always returns the domain point

intersect(start_point, end_point)

You cannot intersect a point domain

class lepton.domain.Sphere

Sphere or spherical shell domain

Sphere(center, outer_radius, inner_radius=0)

center – Center point of sphere (3-number sequence)

outer_radius – Radius of outermost surface of sphere

inner_radius – If greater than zero, the radius of the innermost suface of the spherical shell. must be <= outer_radius

closest_point_to(point) → point, normal

Returns the closest point on the sphere’s surface to the supplied point.

generate() → Vector

Return a random point inside the sphere or spherical shell

intersect(seg_start, seg_end) → point, normal

Intersect the line segment with the sphere and return the first intersection point and normal vector pointing into space from the sphere intersection point. If the sphere has an inner radius, the intersection can occur on the inner or outer shell surface.

If the line does not intersect, return (None, None)

Writing your own domains

You can write your own domains in Python.

Domains should fulfil the following interface contract:

class lepton.domain.Domain

Domain abstract base class

closest_point_to(point)

Return the closest point in the domain to the given point and the surface normal vector at that point. If the given point is in the domain, return the point and a null normal vector.

Note the closest point may not in the domain, if there are multiple points in the domain that are closest. In that case return the average of the closest points and a null normal vector.

generate()

Return a point within the domain as a 3-tuple. For domains with a non-zero volume, ‘point in domain’ is guaranteed to return true.

intersect(start_point, end_point)

For the line segment defined by the start and end point specified (coordinate 3-tuples), return the point closest to the start point where the line segment intersects surface of the domain, and the surface normal unit vector at that point as a 2-tuple. If the line segment does not intersect the domain, return the 2-tuple (None, None).

Only 2 or 3 dimensional domains may be intersected.

Note performance is more important than absolute accuracy with this method, so approximations are acceptable.