sources

Image and video data generation.

Basic Usage: Sources

The image generation source classes (sources) are used to create image data. Using a source is a two-step process: initialize the source then generate the data with pjimg.sources.Source.fill().

Usage:

>>> box = Box((0, 1, 1), (1, 2, 2), 1.0)
>>> box.fill((1, 4, 4))
array([[[0., 0., 0., 0.],
        [0., 1., 1., 0.],
        [0., 1., 1., 0.],
        [0., 0., 0., 0.]]])

Source Classes

An image data source is a class with a Source.fill() method that generates image data.

pjimg.sources.Source()

A source of image data.

Patterns

Sources that generate shapes, text, and other fully deterministic image and video data.

class pjimg.sources.Box(origin: Sequence[int], dimensions: Sequence[int], color: float = 1.0)

Draw a box.

Parameters:

• origin – The location of the upper left corner of the box.

• dimensions – The size of the box in three dimensions.

• color – The color of the box. This is a float within the range 0 <= x <= 1.

Returns:

A Box object.

Return type:

sources.patterns.Box

Usage:

>>> # Create an image of a gray rectangle in the middle of a
>>> # 1280x720 image.
>>> size = (1, 720, 1280)
>>> origin = (n // 4 for n in size)
>>> dimensions = (1, *(n // 2 for n in size[Y:]))
>>> source = Box(origin=origin, dimensions=dimensions, color=0.5)
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.Gradient(direction: str = 'h', stops: Sequence[float] = (0, 0, 1, 1))

Generate a simple gradient.

Parameters:

• direction – (Optional.) This should be ‘h’ for a horizontal gradient or ‘v’ for a vertical gradient.

• stops – (Optional.) A gradient stop sets the color at a position in the gradient. This is a one-dimensional sequence of numbers. It’s parsed in pairs, with the first number being the position of the stop and the second being the color value of the stop.

Returns:

Gradient object.

Return type:

sources.patterns.Gradient

Usage:

>>> # Create a horizontal gradient with multiple stops in a
>>> # 1280x720 image.
>>> size = (1, 720, 1280)
>>> stops = [
...     0.1, 0.0,
...     0.2, 1.0,
...     0.3, 0.0,
...     0.8, 1.0,
...     0.9, 0.0,
... ]
>>> source = Gradient(direction='h', stops=stops)
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.Hexes(radius: int, cells: bool = True, round: bool = False)

Fill a space with hexagonal cells.

Parameters:

• radius – The distance from the center of a cell to the center of each of the sides of the cell.

• cells – (Optional.) Whether the color of a pixel is based only on the distance to the nearest center point or if it is set to black if it’s further away than the radius. When true, Hexes will produce square cell-like structures rather than spheres.

• round – (Optional.) Whether to apply a circular easing function to output to give the appearance of the exterior of a sphere.

Returns:

A sources.Hexes object.

Return type:

sources.patterns.Hexes

Usage:

>>> # Create a hexagonal grid of cells in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> radius = size[Y] // 8
>>> source = Hexes(radius=radius)
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.Lines(direction: str = 'h', length: float = 64)

Generate simple lines.

Parameters:

• direction – (Optional.) This should be ‘h’ for a horizontal gradient or ‘v’ for a vertical gradient.

• length – (Optional.) The distance between each line. Note: This parameter is hostile to proportional resizing. This is because one is subtracted from it when determining the period of the line. To allow for proportional resizing, add one to the value before passing it to this parameter.

Returns:

Lines object.

Return type:

sources.patterns.Lines

Usage:

>>> # Create a series of vertical lines in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> length = (size[X] / 8) - (size[Y] / 64)
>>> source = Lines(direction='v', length=length)
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.Radials(length: float, growth: str = 'l')

Generates concentric radial gradients.

Parameters:

• length – The radius of the innermost circle.

• growth – (Optional.) Either the string ‘linear’ or the string ‘geometric’. Determines whether the distance between each circle remains constant (linear) or increases (geometric). Defaults to linear.

Returns:

Radials object.

Return type:

sources.patterns.Radials

Usage:

>>> # Create a series of concentric radial gradients in a
>>> # 1280x720 images.
>>> size = (1, 720, 1280)
>>> length = size[Y] / 16
>>> source = Radials(length=length, growth='g')
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.Rays(count: int, offset: float = 0)

Create rays that generate from a central point.

Parameters:

• count – The number of rays to generate.

• offset – (Optional.) Rotate the rays around the generation point. This is measured in radians.

Returns:

Rays object.

Return type:

sources.patterns.Rays

Usage:

>>> # Create seven rays emanating from the center of a 1280x720
>>> # image.
>>> size = (1, 720, 1280) 
>>> source = Rays(count=7, offset=0.178)
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.Regular(sides: int, rho: float, rotate: float = 0.0, color: float = 1.0, bg_color: float = 0.0, antialias: bool = False)

Create a regular polygon.

Parameters:

• sides – The number of sides of the polygon.

• rho – The distance from the center of the polygon to a vertex of the polygon.

• rotate – (Optional.) How much to rotate the polygon in radians. The default is 0.0.

• color – (Optional.) The color of the polygon. Default is 1.0.

• antialias – (Optional.) Whether to antialias the edge of the polygon. Default is True.

Usage:

>>> # Create a pentagon in a 1280x720 image.
>>> size = (1, 720, 1280) 
>>> source = Regular(5, size[1] / 2)
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.Rings(radius: float, width: float, gap: float = 0, count: int = 1, count_offset: int = 0)

Create a series of concentric circles.

Parameters:

• radius – The radius of the first ring, which is the ring closest to the center. It is measured from the origin point of the rings to the middle of the band of the first ring.

• width – The width of each band of the ring. It’s measured from each edge of the band.

• gap – (Optional.) The distance between each ring. It’s measured from the middle of the first band to the middle of the next band. The default value of zero causes the rings to draw on top of each other, making it look like there is only one ring.

• count – (Optional.) The number of rings to draw. The default is one.

• count_offset – (Optional.) Set to 1 for backwards compatibility with pjinoise.

Returns:

Rings object.

Return type:

sources.patterns.Rings

Usage:

>>> # Create a series of concentric rings in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> radius = size[X] / 6
>>> width = size[X] / 12
>>> gap = size[X] / 18
>>> count = 6
>>> source = Rings(radius=radius, width=width, gap=gap, count=count)
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.Solid(color: float)

Fill a space with a solid color.

Parameters:

color – The color to use for the fill. Zero is black. One is white. The values between are values of gray.

Returns:

Solid object.

Return type:

pjinoise.sources.Solid

Usage:

>>> # Create a solid gray 1280x720 image.
>>> size = (1, 1280, 720)
>>> source = Solid(color=0.25)
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.Spheres(radius: float, offset: str = '', cells: bool = False, round: bool = True)

Fill a space with a series of spots.

Parameters:

• radius – The radius of an individual spot.

• offset – (Optional.) Whether alternating rows or columns should be offset. Set to ‘x’ for rows to be offset. Set to ‘y’ for columns to be offset. It defaults to None for no offset.

• cells – (Optional.) Whether the color of a pixel is based only on the distance to the nearest center point or if it is set to black if it’s further away than the radius. When true, Spheres will produce square cell-like structures rather than spheres.

• round – (Optional.) Whether to apply a circular easing function to output to give the appearance of the exterior of a sphere.

Returns:

Spheres object.

Return type:

sources.patterns.Spheres

Usage:

>>> # Create a square grid of cells in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> radius = size[Y] / 16
>>> source = Spheres(radius=radius, offset='')
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.Spot(radius: float, *args, **kwargs)

Fill a space with a spot.

Parameters:

radius – The radius of the spot.

Returns:

Spot object.

Return type:

sources.patterns.Spot

Usage:

>>> # Create a radial gradient centered in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> radius = size[Y] * 2 / 3
>>> source = Spot(radius=radius)
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.Text(text: str, font: str = 'Verdana', size: int = 10, face: int = 0, encoding: str = 'unic', layout_engine: str = '', origin: tuple[float, float] = (0, 0), start: int = 0, duration: int | None = None, fill_color: float = 1, bg_color: float = 0, spacing: float = 0.2, spacing_mode: str = 'proportional', align: Literal['left', 'center', 'right'] = 'left', stroke_width: int = 0, stroke_fill: int = 0)

Place text within the image.

Parameters:

• text – The text to add.

• font – (Optional.) The font for the text. It uses the fonts available to your system.

• size – (Optional.) The size of the text in points.

• face – (Optional.) The index number of the face of the font. See PIL.ImageFont.truetype().

• encoding – (Optional.) The encoding for the font. See PIL.ImageFont.truetype().

• layout_engine – (Optional.) The layout engine for the font. See PIL.ImageFont.truetype().

• origin – (Optional.) The starting position for the test.

• start – (Optional.) The number of blank frames before the text appears in video.

• duration – (Optional.) The number of frames the texts is visible in video.

• fill_color – (Optional.) The brightness of the text.

• bg_color – (Optional.) The color of the background behind the text.

• spacing – (Optional.) The number of pixels between lines of text. Basically the leading minus the size.

• spacing – (Optional.) How to automatically calculate the spacing.

• align – (Optional.) The horizontal alignment of the text.

• stroke_width – (Optional.) The width of the stroke around the characters.

• stroke_color – (Optional.) The color to use for the stroke.

Returns:

A Text object.

Return type:

sources.patterns.Text

Usage:

>>> # Create the word "SPAM" in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> origin = (size[X] / 2 - 107, size[Y] / 2 - 52)
>>> source = Text(
...     text='SPAM',
...     font='Helvetica',
...     size=72,
...     face=1,
...     layout_engine='basic',
...     origin=origin,
...     fill_color=0.75,
...     bg_color=0.25,
...     align='center',
...     stroke_width=5,
...     stroke_fill=0x00
... )
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.Waves(unit: int = 1279, angle: float = 0, wavelength: float = 1, warp: Callable[[ndarray[tuple[int, ...], dtype[float64]]], ndarray[tuple[int, ...], dtype[float64]]] | None = None, radial: bool = False)

Generates wave patterns using a cosine function.

Parameters:

• unit – (Optional.) The number of pixels in a unit of distance of the wave. It defaults to 1279 pixels.

• angle – (Optional.) The angle in degrees of the wave. An angle of 0 creates vertical bars. An angle of 90 creates horizontal bars. It defaults to 0.

• wavelength – (Optional.) The number peaks that occur within a unit. Defaults to 1.

• warp – (Optional.) A function that accepts an image array and returns an image array. This function is used to alter the space the wave is propagating through, allowing you to change the wavelength based on the position in the image. Defaults to None.

• radial – (Optional.) When true, the waves should radiate from a central point in a circular pattern. Defaults to False.

Returns:

Waves object.

Return type:

sources.patterns.Waves

Usage:

>>> # Create a wave pattern in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> unit = 1279
>>> angle = 30.0
>>> wavelength = 5.0
>>> source = Waves(unit, angle=angle, wavelength=wavelength)
>>> img = source.fill(size)

The image data created by the usage example.

tile

Sources that tile shapes over the image.

class pjimg.sources.Tile(pattern: str, radius: int, gap: int, rotation: float = 0.0, color: float = 1.0, color_img: ndarray[tuple[int, ...], dtype[float64]] | None = None, drop: float = 0.0, drop_img: ndarray[tuple[int, ...], dtype[float64]] | None = None, seed: None | int | str | bytes = None)

Tile a space with polygons.

Parameters:

• pattern – The tiling pattern to use when tiling the space. Valid values are available as the keys of the sources.tile_patterns registry.

• radius – The size of an individual tile. What this measures will depend on the specific tile pattern, however in simple patterns it should be the distance from the center of a single tile to the vertices of the tile in pixels. The name is a reference to the distance being the radius of the circle enclosing the tile.

• gap – The distance between two neighboring tiles. What this measures will depend on the specific tile pattern, however in simple patterns it should be the distance between from the side of one tile to the closest point on the neighboring tile.

• rotation – (Optional.) The angle to rotate each individual tile in radians. (Future versions may change this to degrees for consistency.) Defaults to 0.

• color – (Optional.) The color of each tile. Defaults to 1.0.

• color_img – (Optional.) Image data that is used to determine the color of each tile. The color is based on the average of the values within the same area the tile would be in on the final image. Defaults to None.

• drop – (Optional.) The likelihood a tile is not placed. This is a percentage chance within the range 0.0 <= x <= 1.0. Defaults to 0.0.

• drop_img – (Optional.) Image data that is used to determine the likelihood a tile is dropped from the pattern. The drop percentage is based on the average of the values within the same area the tile would be in on the final image. Defaults to None.

• seed – (Optional.) A seed value for the random number generator used to determine whether tiles are dropped. Defaults to the generator running without a seed.

Returns:

:class:Tile object.

Return type:

sources.tile.Tile

Usage:

>>> # Create a tiled pattern in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> pattern = 'triangle'
>>> radius = 20
>>> gap = 3
>>> source = Tile(pattern=pattern, radius=radius, gap=gap)
>>> img = source.fill(size)

The image data created by the usage example.

Noises

Sources that generate psuedorandom noise.

class pjimg.sources.Noise(seed: None | int | str | bytes = None)

Create continuous-uniformly distributed random noise with a seed value to allow the noise to be regenerated in a predictable way.

Parameters:

seed – (Optional.) An int, bytes, or string used to seed therandom number generator used to generate the image data. If no value is passed, the RNG will not be seeded, so serialized versions of this source will not product the same values. Note: strings that are passed to seed will be converted to UTF-8 bytes before being converted to integers for seeding.

Returns:

:class:Noise object.

Return type:

sources.noise.Noise

Usage:

>>> # Create static to fill a 1280x720 image.
>>> size = (1, 720, 1280)
>>> source = Noise(seed='spam')
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.Embers(depth: int = 1, threshhold: float = 0.9998, *args, **kwargs)

Fill a space with bright points or dots that resemble embers or stars.

Parameters:

• depth – (Optional.) The number of different sizes of dots to create.

• threshold – (Optional.) Embers starts by generating random values for each point. This sets the minimum value to keep in the output. It’s a percentage, and the lower the value the more points are kept.

• seed – (Optional.) An int, bytes, or string used to seed therandom number generator used to generate the image data. If no value is passed, the RNG will not be seeded, so serialized versions of this source will not product the same values. Note: strings that are passed to seed will be converted to UTF-8 bytes before being converted to integers for seeding.

• ease – (Optional.) The easing function to use on the generated noise.

Returns:

Embers object.

Return type:

sources.noise.Embers

Usage:

>>> # Create embers in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> source = Embers(depth=6, seed='spam')
>>> img = source.fill(size)

The image data created by the usage example.

Unit Noise

Unit noise splits the image space into a grid of units, then randomly distributes values at the positions on the grid. Image data is then generated using an easing function that provides values for the pixels between the positions on the grid.

class pjimg.sources.UnitNoise(unit: Sequence[float], min: int = 0, max: int = 255, repeats: int = 0, seed: None | int | str | bytes = None, table: Sequence[int] | None = None)

Create image noise that is based on a unit grid.

Parameters:

• unit – The number of pixels between vertices along an axis on the unit grid. The vertices are the locations where colors for the gradient are set. This is involved in setting the maximum size of noise that can be generated from the object.

• min – (Optional.) The minimum value of a vertex of the unit grid. This is involved in setting the maximum size of noise that can be generated from the object.

• max – (Optional.) The maximum value of a vertex of the unit grid. This is involved in setting the maximum size of noise that can be generated from the object.

• repeats – (Optional.) The number of times each value can appear on the unit grid. This is involved in setting the maximum size of noise that can be generated from the object.

• seed – (Optional.) An int, bytes, or string used to seed the random number generator used to generate the image data. If no value is passed, the RNG will not be seeded, so serialized versions of this source will not produce the same values. Note: strings that are passed to seed will be converted to UTF-8 bytes before being converted to integers for seeding.

• table – (Optional.) A table of values to use when generating the image data. If no value is passed, the table will be generated randomly. Default is None.

Returns:

An instance of UnitNoise.

Return type:

sources.unitnoise.UnitNoise

Usage:

>>> # Create unit noise in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> unit = (1, size[Y] // 5, size[Y] // 5)
>>> source = UnitNoise(unit=unit, seed='spam')
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.CosineNoise(unit: Sequence[float], min: int = 0, max: int = 255, repeats: int = 0, seed: None | int | str | bytes = None, table: Sequence[int] | None = None)

Create image noise that is based on a unit grid and smoothed with a cosine ease.

Parameters:

• unit – The number of pixels between vertices along an axis on the unit grid. The vertices are the locations where colors for the gradient are set. This is involved in setting the maximum size of noise that can be generated from the object.

• min – (Optional.) The minimum value of a vertex of the unit grid. This is involved in setting the maximum size of noise that can be generated from the object.

• max – (Optional.) The maximum value of a vertex of the unit grid. This is involved in setting the maximum size of noise that can be generated from the object.

• repeats – (Optional.) The number of times each value can appear on the unit grid. This is involved in setting the maximum size of noise that can be generated from the object.

• seed – (Optional.) An int, bytes, or string used to seed the random number generator used to generate the image data. If no value is passed, the RNG will not be seeded, so serialized versions of this source will not produce the same values. Note: strings that are passed to seed will be converted to UTF-8 bytes before being converted to integers for seeding.

• table – (Optional.) A table of values to use when generating the image data. If no value is passed, the table will be generated randomly. Default is None.

Returns:

An instance of CosineNoise.

Return type:

sources.unitnoise.CosineNoise

Usage:

>>> # Create unit noise in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> unit = (1, size[Y] // 5, size[Y] // 5)
>>> source = CosineNoise(unit=unit, seed='spam')
>>> img = source.fill(size)

The image data created by the usage example.

Curtains

Curtains are unit noise that is generated in only one dimension of an image.

class pjimg.sources.CosineCurtains(unit: Sequence[float], min: int = 0, max: int = 255, repeats: int = 0, seed: None | int | str | bytes = None, table: Sequence[int] | None = None)

Unit noise that creates vertical lines with a cosine-based ease on the color change between grid points, making them appear to flow more like curtains.

Parameters:

• unit – The number of pixels between vertices along an axis on the unit grid. The vertices are the locations where colors for the gradient are set. This is involved in setting the maximum size of noise that can be generated from the object.

• min – (Optional.) The minimum value of a vertex of the unit grid. This is involved in setting the maximum size of noise that can be generated from the object.

• max – (Optional.) The maximum value of a vertex of the unit grid. This is involved in setting the maximum size of noise that can be generated from the object.

• repeats – (Optional.) The number of times each value can appear on the unit grid. This is involved in setting the maximum size of noise that can be generated from the object.

• seed – (Optional.) An int, bytes, or string used to seed therandom number generator used to generate the image data. If no value is passed, the RNG will not be seeded, so serialized versions of this source will not produce the same values. Note: strings that are passed to seed will be converted to UTF-8 bytes before being converted to integers for seeding.

Returns:

An instance of CosineCurtains.

Return type:

sources.unitnoise.CosineCurtains

Usage:

>>> # Create rounded curtains in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> unit = (1, size[Y] // 5, size[Y] // 5)
>>> source = CosineCurtains(unit=unit, seed='spam')
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.Curtains(unit: Sequence[float], min: int = 0, max: int = 255, repeats: int = 0, seed: None | int | str | bytes = None, table: Sequence[int] | None = None)

Unit noise that creates vertical lines, like curtains.

Parameters:

• unit – The number of pixels between vertices along an axis on the unit grid. The vertices are the locations where colors for the gradient are set. This is involved in setting the maximum size of noise that can be generated from the object.

• min – (Optional.) The minimum value of a vertex of the unit grid. This is involved in setting the maximum size of noise that can be generated from the object.

• max – (Optional.) The maximum value of a vertex of the unit grid. This is involved in setting the maximum size of noise that can be generated from the object.

• repeats – (Optional.) The number of times each value can appear on the unit grid. This is involved in setting the maximum size of noise that can be generated from the object.

• seed – (Optional.) An int, bytes, or string used to seed therandom number generator used to generate the image data. If no value is passed, the RNG will not be seeded, so serialized versions of this source will not produce the same values. Note: strings that are passed to seed will be converted to UTF-8 bytes before being converted to integers for seeding.

Returns:

An instance of Curtains.

Return type:

sources.unitnoise.Curtains

Usage:

>>> # Create sharp curtains in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> unit = (1, size[Y] // 5, size[Y] // 5)
>>> source = Curtains(unit=unit, seed='spam')
>>> img = source.fill(size)

The image data created by the usage example.

Octave Noise

Octave noise creates more intricate patterns by adding together multiple layers of unit noise.

class pjimg.sources.OctaveUnitNoise(octaves: int = 4, persistence: float = 8, amplitude: float = 8, frequency: float = 2, unit: Sequence[float] = (1024, 1024, 1024), min: int = 0, max: int = 255, repeats: int = 1, seed: None | int | str | bytes = None, table: Sequence[int] | None = None)

A source for octave noise. Parameters are similar to the UnitNoise being octaved, with the following additions.

Parameters:

• octaves – The number of octaves of noise in the image. An octave is a layer of the noise with a different number of points added on top of other layers of noise.

• persistence – How the weight of each octave changes.

• amplitude – The weight of the first octave.

• frequency – How the number of points in each octave changes.

Returns:

An pjimg.sources.OctaveUnitNoise object.

Return type:

pjimg.sources.OctaveUnitNoise

Usage:

>>> # Create OctaveUnitNoise noise in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> unit = (1, size[Y] // 5, size[Y] // 5)
>>> source = OctaveUnitNoise(
>>>     unit=unit,
>>>     octaves=3,
>>>     persistence=-4,
>>>     amplitude=24,
>>>     frequency=4,
>>>     seed='spam'
>>> )
>>> img = source.fill(size)

Output of OctaveUnitNoise.

class pjimg.sources.OctaveCosineCurtains(octaves: int = 4, persistence: float = 8, amplitude: float = 8, frequency: float = 2, unit: Sequence[float] = (1024, 1024, 1024), min: int = 0, max: int = 255, repeats: int = 1, seed: None | int | str | bytes = None, table: Sequence[int] | None = None)

A source for octave noise. Parameters are similar to the UnitNoise being octaved, with the following additions.

Parameters:

• octaves – The number of octaves of noise in the image. An octave is a layer of the noise with a different number of points added on top of other layers of noise.

• persistence – How the weight of each octave changes.

• amplitude – The weight of the first octave.

• frequency – How the number of points in each octave changes.

Returns:

An pjimg.sources.OctaveCosineCurtains object.

Return type:

pjimg.sources.OctaveCosineCurtains

Usage:

>>> # Create OctaveCosineCurtains noise in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> unit = (1, size[Y] // 5, size[Y] // 5)
>>> source = OctaveCosineCurtains(
>>>     unit=unit,
>>>     octaves=3,
>>>     persistence=-4,
>>>     amplitude=24,
>>>     frequency=4,
>>>     seed='spam'
>>> )
>>> img = source.fill(size)

Output of OctaveCosineCurtains.

class pjimg.sources.OctaveCurtains(octaves: int = 4, persistence: float = 8, amplitude: float = 8, frequency: float = 2, unit: Sequence[float] = (1024, 1024, 1024), min: int = 0, max: int = 255, repeats: int = 1, seed: None | int | str | bytes = None, table: Sequence[int] | None = None)

A source for octave noise. Parameters are similar to the UnitNoise being octaved, with the following additions.

Parameters:

• octaves – The number of octaves of noise in the image. An octave is a layer of the noise with a different number of points added on top of other layers of noise.

• persistence – How the weight of each octave changes.

• amplitude – The weight of the first octave.

• frequency – How the number of points in each octave changes.

Returns:

An pjimg.sources.OctaveCurtains object.

Return type:

pjimg.sources.OctaveCurtains

Usage:

>>> # Create OctaveCurtains noise in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> unit = (1, size[Y] // 5, size[Y] // 5)
>>> source = OctaveCurtains(
>>>     unit=unit,
>>>     octaves=3,
>>>     persistence=-4,
>>>     amplitude=24,
>>>     frequency=4,
>>>     seed='spam'
>>> )
>>> img = source.fill(size)

Output of OctaveCurtains.

class pjimg.sources.BorktaveUnitNoise(octaves: int = 4, persistence: float = 8, amplitude: float = 8, frequency: float = 2, unit: Sequence[float] = (1024, 1024, 1024), min: int = 0, max: int = 255, repeats: int = 1, seed: None | int | str | bytes = None, table: Sequence[int] | None = None)

A source for octave noise. Parameters are similar to the UnitNoise being octaved, with the following additions.

Parameters:

• octaves – The number of octaves of noise in the image. An octave is a layer of the noise with a different number of points added on top of other layers of noise.

• persistence – How the weight of each octave changes.

• amplitude – The weight of the first octave.

• frequency – How the number of points in each octave changes.

Returns:

An pjimg.sources.BorktaveUnitNoise object.

Return type:

pjimg.sources.BorktaveUnitNoise

Usage:

>>> # Create BorktaveUnitNoise noise in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> unit = (1, size[Y] // 5, size[Y] // 5)
>>> source = BorktaveUnitNoise(
>>>     unit=unit,
>>>     octaves=4,
>>>     persistence=8,
>>>     amplitude=8,
>>>     frequency=-1.5,
>>>     seed='spam'
>>> )
>>> img = source.fill(size)

Output of BorktaveUnitNoise.

Warning

This octave class is borked. That means the operation used to calculate the unit size for each octave multiplies by the frequency rather than divides. This reproduces a bug in earlier versions of this code which caused some interesting behavior. It generates output just fine. It just won’t be the same output generated with the real octave algorithm.

class pjimg.sources.BorktaveCosineNoise(octaves: int = 4, persistence: float = 8, amplitude: float = 8, frequency: float = 2, unit: Sequence[float] = (1024, 1024, 1024), min: int = 0, max: int = 255, repeats: int = 1, seed: None | int | str | bytes = None, table: Sequence[int] | None = None)

A source for octave noise. Parameters are similar to the UnitNoise being octaved, with the following additions.

Parameters:

• octaves – The number of octaves of noise in the image. An octave is a layer of the noise with a different number of points added on top of other layers of noise.

• persistence – How the weight of each octave changes.

• amplitude – The weight of the first octave.

• frequency – How the number of points in each octave changes.

Returns:

An pjimg.sources.BorktaveCosineNoise object.

Return type:

pjimg.sources.BorktaveCosineNoise

Usage:

>>> # Create BorktaveCosineNoise noise in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> unit = (1, size[Y] // 5, size[Y] // 5)
>>> source = BorktaveCosineNoise(
>>>     unit=unit,
>>>     octaves=4,
>>>     persistence=8,
>>>     amplitude=8,
>>>     frequency=-1.5,
>>>     seed='spam'
>>> )
>>> img = source.fill(size)

Output of BorktaveCosineNoise.

Warning

This octave class is borked. That means the operation used to calculate the unit size for each octave multiplies by the frequency rather than divides. This reproduces a bug in earlier versions of this code which caused some interesting behavior. It generates output just fine. It just won’t be the same output generated with the real octave algorithm.

class pjimg.sources.BorktaveCosineCurtains(octaves: int = 4, persistence: float = 8, amplitude: float = 8, frequency: float = 2, unit: Sequence[float] = (1024, 1024, 1024), min: int = 0, max: int = 255, repeats: int = 1, seed: None | int | str | bytes = None, table: Sequence[int] | None = None)

A source for octave noise. Parameters are similar to the UnitNoise being octaved, with the following additions.

Parameters:

• octaves – The number of octaves of noise in the image. An octave is a layer of the noise with a different number of points added on top of other layers of noise.

• persistence – How the weight of each octave changes.

• amplitude – The weight of the first octave.

• frequency – How the number of points in each octave changes.

Returns:

An pjimg.sources.BorktaveCosineCurtains object.

Return type:

pjimg.sources.BorktaveCosineCurtains

Usage:

>>> # Create BorktaveCosineCurtains noise in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> unit = (1, size[Y] // 5, size[Y] // 5)
>>> source = BorktaveCosineCurtains(
>>>     unit=unit,
>>>     octaves=4,
>>>     persistence=8,
>>>     amplitude=8,
>>>     frequency=-1.5,
>>>     seed='spam'
>>> )
>>> img = source.fill(size)

Output of BorktaveCosineCurtains.

Warning

This octave class is borked. That means the operation used to calculate the unit size for each octave multiplies by the frequency rather than divides. This reproduces a bug in earlier versions of this code which caused some interesting behavior. It generates output just fine. It just won’t be the same output generated with the real octave algorithm.

Perlin Noise

Perlin noise is a specific type of unit noise that uses procedures developed by Ken Perlin to provide a more naturalistic look to computer generated images.

class pjimg.sources.Perlin(unit: Sequence[int], min: int = 0, max: int = 255, repeats: int = 1, seed: None | int | str | bytes = None, table: Sequence[int] | None = None)

A class to generate Perlin noise.

Parameters:

• unit – The number of pixels between vertices along an axis on the unit grid. The vertices are the locations where colors for the gradient are set. This is involved in setting the maximum size of noise that can be generated from the object.

• min – (Optional.) The minimum value of a vertex of the unit grid. This is involved in setting the maximum size of noise that can be generated from the object. Unless you have a very good reason, this is probably best left at the default.

• max – (Optional.) The maximum value of a vertex of the unit grid. This is involved in setting the maximum size of noise that can be generated from the object. Unless you have a very good reason, this is probably best left at the default.

• repeats – (Optional.) The number of times each value can appear on the unit grid. This is involved in setting the maximum size of noise that can be generated from the object. Unless you have a very good reason, this is probably best left at the default.

• seed – (Optional.) An int, bytes, or string used to seed therandom number generator used to generate the image data. If no value is passed, the RNG will not be seeded, so serialized versions of this source will not produce the same values. Note: strings that are passed to seed will be converted to UTF-8 bytes before being converted to integers for seeding.

Returns:

:class:Perlin object.

Return type:

sources.perlin.Perlin

Usage:

>>> # Create Perlin noise in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> unit = (1, size[Y] // 5, size[Y] // 5)
>>> source = Perlin(unit=unit, seed='spam')
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.OctavePerlin(octaves: int = 6, persistence: float = -4, amplitude: float = 24, frequency: float = 4, unit: Sequence[float] = (1024, 1024, 1024), min: int = 0, max: int = 255, repeats: int = 1, seed: None | int | str | bytes = None, table: Sequence[int] | None = None)

A source for octave noise. Parameters are similar to the UnitNoise being octaved, with the following additions.

Parameters:

• octaves – The number of octaves of noise in the image. An octave is a layer of the noise with a different number of points added on top of other layers of noise.

• persistence – How the weight of each octave changes.

• amplitude – The weight of the first octave.

• frequency – How the number of points in each octave changes.

Returns:

An pjimg.sources.OctavePerlin object.

Return type:

pjimg.sources.OctavePerlin

Usage:

>>> # Create OctavePerlin noise in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> unit = (1, size[Y] // 5, size[Y] // 5)
>>> source = OctavePerlin(
>>>     unit=unit,
>>>     octaves=3,
>>>     persistence=-4,
>>>     amplitude=24,
>>>     frequency=4,
>>>     seed='spam'
>>> )
>>> img = source.fill(size)

Output of OctavePerlin.

Mazes

A pseudorandomly generated maze.

class pjimg.sources.Maze(unit: Sequence[int], width: float = 0.2, inset: Sequence[int] = (0, 1, 1), origin: str | Sequence[int] = 'tl', min: int = 0, max: int = 255, repeats: int = 1, seed: None | int | str | bytes = None, table: Sequence[int] | None = None)

A class to generate maze-like paths.

Parameters:

• unit – The number of pixels between vertices along an axis. The vertices are the locations where the direction of the path can change.

• width – (Optional.) The width of the path. This is the percentage of the width of the X axis length of the size of the fill. Values over one will probably be weird, but not in a great way.

• inset – (Optional.) Sets how many units from the end of the image to draw the path. Units here refers to the unit parameter from the UnitNoise parent class.

• origin – (Optional.) Where in the grid to start the path. This can be either a descriptive string or a three-dimensional coordinate. It defaults to the top-left corner of the first three-dimensional slice of the data.

• min – (Optional.) The minimum value of a vertex of the unit grid. This is involved in setting the path through the maze.

• max – (Optional.) The maximum value of a vertex of the unit grid. This is involved in setting the path through the maze.

• repeats – (Optional.) The number of times each value can appear on the unit grid. This is involved in setting the maximum size of noise that can be generated from the object.

• seed – (Optional.) An int, bytes, or string used to seed therandom number generator used to generate the image data. If no value is passed, the RNG will not be seeded, so serialized versions of this source will not product the same values. Note: strings that are passed to seed will be converted to UTF-8 bytes before being converted to integers for seeding.

Returns:

Maze object.

Return type:

sources.maze.Maze

Usage:

>>> # Create a maze in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> unit = (1, size[Y] // 18, size[Y] // 18)
>>> source = Maze(unit=unit, seed='spam')
>>> img = source.fill(size)

The image data created by the usage example.

Descriptive Origins

The origin parameter can accept a description of the location instead of direct coordinates. This string must either be two words delimited by a hyphen or two letters. The first position sets the Y axis location can be one of the following options:

• top | t

• middle | m

• bottom | b

The second position sets the X axis position and can be one of the following options:

• left | l

• middle | m

• right | r

class pjimg.sources.AnimatedMaze(unit: Sequence[int], delay: int = 0, linger: int = 0, trace: bool = True, width: float = 0.2, inset: Sequence[int] = (0, 1, 1), origin: str | Sequence[int] = 'tl', min: int = 0, max: int = 255, repeats: int = 1, seed: None | int | str | bytes = None)

Animate the creation of a maze.

Parameters:

• unit – The number of pixels between vertices along an axis. The vertices are the locations where the direction of the path can change.

• delay – (Optional.) The number of frames to wait before starting the animation.

• linger – (Optional.) The number of frames to hold on the last image of the animation.

• trace – (Optional.) Whether to show all of the path that had been walked to this point (True) or just show this step (False).

• width – (Optional.) The width of the path. This is the percentage of the width of the X axis length of the size of the fill. Values over one will probably be weird, but not in a great way.

• inset – (Optional.) Sets how many units from the end of the image to draw the path. Units here refers to the unit parameter from the UnitNoise parent class.

• origin – (Optional.) Where in the grid to start the path. This can be either a descriptive string or a three-dimensional coordinate. It defaults to the top-left corner of the first three-dimensional slice of the data.

• min – (Optional.) The minimum value of a vertex of the unit grid. This is involved in setting the path through the maze.

• max – (Optional.) The maximum value of a vertex of the unit grid. This is involved in setting the path through the maze.

• seed – (Optional.) An int, bytes, or string used to seed therandom number generator used to generate the image data. If no value is passed, the RNG will not be seeded, so serialized versions of this source will not product the same values. Note: strings that are passed to seed will be converted to UTF-8 bytes before being converted to integers for seeding.

Returns:

AnimatedMaze object.

Return type:

sources.maze.AnimatedMaze

class pjimg.sources.OctaveMaze(octaves: int = 4, persistence: float = 8, amplitude: float = 8, frequency: float = 2, unit: Sequence[int] = (1, 20, 20), width: float = 0.2, inset: Sequence[int] = (0, 1, 1), origin: str | Sequence[int] = 'tl', min: int = 0, max: int = 255, repeats: int = 1, seed: None | int | str | bytes = None, table: Sequence[int] | None = None)

Fill a space with octaves of Maze noise.

Maze noise generates a maze-like path within the space.

Parameters:

• octaves – The number of octaves of noise in the image. An octave is a layer of the noise with a different number of points added on top of other layers of noise.

• persistence – How the weight of each octave changes.

• amplitude – The weight of the first octave.

• frequency – How the number of points in each octave changes.

• seed – (Optional.) An int, bytes, or string used to seed therandom number generator used to generate the image data. If no value is passed, the RNG will not be seeded, so serialized versions of this source will not product the same values. Note: strings that are passed to seed will be converted to UTF-8 bytes before being converted to integers for seeding.

Returns:

OctaveMaze object.

Return type:

sources.maze.OctaveMaze

Usage:

>>> # Create octave Maze noise in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> source = OctaveMaze(
...     octaves=3,
...     persistence=6,
...     amplitude=5,
...     frequency=3,
...     points=8,
...     seed='spam'
... )
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.SolvedMaze(unit: Sequence[int], start: str | Sequence[int] = 'tl', end: str | Sequence[int] = 'br', algorithm: str = 'branches', width: float = 0.2, inset: Sequence[int] = (0, 1, 1), origin: str | Sequence[int] = 'tl', min: int = 0, max: int = 255, repeats: int = 1, seed: None | int | str | bytes = None)

Draw a line that shows how to get from one location to another in a maze.

Parameters:

• unit – The number of pixels between vertices along an axis. The vertices are the locations where the direction of the path can change.

• start – (Optional.) The starting location of the path. This can be either a descriptive string or a three-dimensional coordinate. It defaults to the top-left corner of the first three-dimensional slice of the data.

• end – (Optional.) The ending location of the path. This can be either a descriptive string or a three-dimensional coordinate. It defaults to the top-left corner of the first three-dimensional slice of the data.

• width – (Optional.) The width of the path. This is the percentage of the width of the X axis length of the size of the fill. Values over one will probably be weird, but not in a great way.

• inset – (Optional.) Sets how many units from the end of the image to draw the path. Units here refers to the unit parameter from the UnitNoise parent class.

• origin – (Optional.) Where in the grid to start the path. This can be either a descriptive string or a three-dimensional coordinate. It defaults to the top-left corner of the first three-dimensional slice of the data.

• seed – (Optional.) An int, bytes, or string used to seed therandom number generator used to generate the image data. If no value is passed, the RNG will not be seeded, so serialized versions of this source will not product the same values. Note: strings that are passed to seed will be converted to UTF-8 bytes before being converted to integers for seeding.

Returns:

SolvedMaze object.

Return type:

sources.maze.SolvedPath

Usage:

>>> # Create the line showing a solution for a maze in a
>>> # 1280x720 image.
>>> size = (1, 720, 1280)
>>> unit = (1, size[Y] // 18, size[Y] // 18)
>>> source = SolvedMaze(unit=unit, seed='spam')
>>> img = source.fill(size)

The image data created by the usage example.

Descriptive Origins

The origin parameter can accept a description of the location instead of direct coordinates. This string must either be two words delimited by a hyphen or two letters. The first position sets the Y axis location can be one of the following options:

• top | t

• middle | m

• bottom | b

The second position sets the X axis position and can be one of the following options:

• left | l

• middle | m

• right | r

Worley Noise

Worley noise scatters a series of points across the image space. Image data is generated based on the distance from a pixel to the nearest point.

class pjimg.sources.Worley(points: int, volume: Sequence[int] | None = None, origin: Sequence[int] = (0, 0, 0), seed: None | int | str | bytes = None)

Fill a space with Worley noise.

Worley noise is a type of cellular noise. The color value of each pixel within the space is determined by the distance from the pixel to the nearest of a set of randomly located points within the image. This creates structures within the noise that look like cells or pits.

This implementation is heavily optimized from code found here: https://code.activestate.com/recipes/578459-worley-noise-generator/

Parameters:

• points – The number of cells in the image. A cell is a randomly placed point and the range of pixels that are closer to it than any other point.

• volume – (Optional.) The size of the volume that the points will be placed in. The default is for them to be evenly spread through the space generated during the fill.

• origin – (Optional.) The location of the upper-top-left corner of the volume that contains the points. This defaults to the upper-top-left corner of the space generated during the fill.

• seed – (Optional.) An int, bytes, or string used to seed therandom number generator used to generate the image data. If no value is passed, the RNG will not be seeded, so serialized versions of this source will not product the same values. Note: strings that are passed to seed will be converted to UTF-8 bytes before being converted to integers for seeding.

Returns:

Worley object.

Return type:

sources.worley.Worley

Usage:

>>> # Create Worley noise in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> source = Worley(points=20, seed='spam')
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.WorleyCell(points: int, volume: Sequence[int] | None = None, origin: Sequence[int] = (0, 0, 0), seed: None | int | str | bytes = None, antialias: bool = False)

Fill a space with Worley noise that fills each cell with a solid color.

Worley noise is a type of cellular noise. The color value of each pixel within the space is determined by the distance from the pixel to the nearest of a set of randomly located points within the image. This creates structures within the noise that look like cells or pits.

This implementation is heavily optimized from code found here: https://code.activestate.com/recipes/578459-worley-noise-generator/

Parameters:

• points – The number of cells in the image. A cell is a randomly placed point and the range of pixels that are closer to it than any other point.

• volume – (Optional.) The size of the volume that the points will be placed in. The default is for them to be evenly spread through the space generated during the fill.

• origin – (Optional.) The location of the upper-top-left corner of the volume that contains the points. This defaults to the upper-top-left corner of the space generated during the fill.

• seed – (Optional.) An int, bytes, or string used to seed therandom number generator used to generate the image data. If no value is passed, the RNG will not be seeded, so serialized versions of this source will not product the same values. Note: strings that are passed to seed will be converted to UTF-8 bytes before being converted to integers for seeding.

• antialias – (Optional.) Whether to soften the edges of the cell boundaries. Essentially, if the difference between the distances to the two closest seeds is less than one pixel, the color will be a mix of the two seeds. This can cause unexpected results when two seeds are next to each other. Defaults to false.

Returns:

WorleyCell object.

Return type:

sources.worley.WorleyCell

Usage:

>>> # Create Worley cell noise in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> source = WorleyCell(points=20, seed='spam')
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.OctaveWorley(octaves: int = 4, persistence: float = 8, amplitude: float = 8, frequency: float = 2, points: int = 10, volume: Sequence[int] | None = None, origin: Sequence[int] = (0, 0, 0), seed: None | int | str | bytes = None)

Fill a space with octaves of Worley noise.

Worley noise is a type of cellular noise. The color value of each pixel within the space is determined by the distance from the pixel to the nearest of a set of randomly located points within the image. This creates structures within the noise that look like cells or pits.

This implementation is heavily optimized from code found here: https://code.activestate.com/recipes/578459-worley-noise-generator/

Parameters:

• octaves – The number of octaves of noise in the image. An octave is a layer of the noise with a different number of points added on top of other layers of noise.

• persistence – How the weight of each octave changes.

• amplitude – The weight of the first octave.

• frequency – How the number of points in each octave changes.

• points – The number of cells in the image. A cell is a randomly placed point and the range of pixels that are closer to it than any other point.

• volume – (Optional.) The size of the volume that the points will be placed in. The default is for them to be evenly spread through the space generated during the fill.

• origin – (Optional.) The location of the upper-top-left corner of the volume that contains the points. This defaults to the upper-top-left corner of the space generated during the fill.

• seed – (Optional.) An int, bytes, or string used to seed therandom number generator used to generate the image data. If no value is passed, the RNG will not be seeded, so serialized versions of this source will not product the same values. Note: strings that are passed to seed will be converted to UTF-8 bytes before being converted to integers for seeding.

Returns:

OctaveWorley object.

Return type:

sources.worley.OctaveWorley

Usage:

>>> # Create octave Worley noise in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> source = OctaveWorley(
...     octaves=3,
...     persistence=6,
...     amplitude=5,
...     frequency=3,
...     points=8,
...     seed='spam'
... )
>>> img = source.fill(size)

The image data created by the usage example.

class pjimg.sources.OctaveWorleyCell(octaves: int = 4, persistence: float = 8, amplitude: float = 8, frequency: float = 2, points: int = 10, volume: Sequence[int] | None = None, origin: Sequence[int] = (0, 0, 0), seed: None | int | str | bytes = None, antialias: bool = False)

Fill a space with octaves of Worley cell noise.

Worley noise is a type of cellular noise. The color value of each pixel within the space is determined by the distance from the pixel to the nearest of a set of randomly located points within the image. This creates structures within the noise that look like cells or pits.

This implementation is heavily optimized from code found here: https://code.activestate.com/recipes/578459-worley-noise-generator/

Parameters:

• octaves – The number of octaves of noise in the image. An octave is a layer of the noise with a different number of points added on top of other layers of noise.

• persistence – How the weight of each octave changes.

• amplitude – The weight of the first octave.

• frequency – How the number of points in each octave changes.

• points – The number of cells in the image. A cell is a randomly placed point and the range of pixels that are closer to it than any other point.

• volume – (Optional.) The size of the volume that the points will be placed in. The default is for them to be evenly spread through the space generated during the fill.

• origin – (Optional.) The location of the upper-top-left corner of the volume that contains the points. This defaults to the upper-top-left corner of the space generated during the fill.

• seed – (Optional.) An int, bytes, or string used to seed therandom number generator used to generate the image data. If no value is passed, the RNG will not be seeded, so serialized versions of this source will not product the same values. Note: strings that are passed to seed will be converted to UTF-8 bytes before being converted to integers for seeding.

• antialias – (Optional.) Whether to soften the edges of the cell boundaries. Essentially, if the difference between the distances to the two closest seeds is less than one pixel, the color will be a mix of the two seeds. This can cause unexpected results when two seeds are next to each other. Defaults to false.

Returns:

OctaveWorleyCell object.

Return type:

sources.worley.OctaveWorleyCell

Usage:

>>> # Create octave Worley cell noise in a 1280x720 image.
>>> size = (1, 720, 1280)
>>> source = OctaveWorleyCell(
...     octaves=3,
...     persistence=6,
...     amplitude=5,
...     frequency=3,
...     points=8,
...     seed='spam'
... )
>>> img = source.fill(size)

The image data created by the usage example.

Source Utilities

Decorators

Decorators for pjimg.sources.

pjimg.sources.register(registry: dict[str, type[TilePattern]]) → Callable[[type[TilePattern]], type[TilePattern]]

Registers the decorated function under the function’s name in the given registry dictionary.

Parameters:

registry – The registry to register the given class in.

Returns:

The registration class pointed to the given registry.

Return type:

class