Meet the Morphobes (morphin' microbes): a parametric library of microbe-like multidimensional visual objects

Morphobes are reproducible, editable micro-organism-like stimuli (SVG + PNG) for cognitive neuroscience experiments. The overall shape areas (px²) are identical, and colours are approximately iso-luminant, minimising non-dimensional confounds. The generator independently varies four dimensions:

• 12 Shapes: radial-Fourier body contours, aspect ratio, asymmetry, and rotation. Overall surface area is identical.
• 7 Appendages (like cilia): no appendages or one of six appendage morphologies.
• 5 Textures: smooth, spots, stripes, waves, or cells.
• 8 Colours: eight approximately equal-lightness CIELCh palette entries.

See the references below for previous work, but they are similar to the stimuli used in the brain explorer set-shifting game. Each generated morphobes dataset includes editable SVG files, optional PNG renders, body and whole-object masks, flat CSV files, and structured JSON metadata.

Requirements

• Python 3.14 or later, as specified in pyproject.toml.
• uv to create the environment and install dependencies.

Install the project dependencies from the repository root:

uv sync

All commands below should be run from the repository root. uv run will use the project environment automatically.

Generate A Dataset

Create a 48-item random library using every current level in each catalogue:

uv run python procedural_microorganisms.py \
	--out stimuli_random \
	--mode random \
	--n 48 \
	--seed 1234 \
	--png \
	--contact-sheet

Create a balanced factorial dataset. Every combination of the selected levels is rendered, with two deterministic exemplars for every combination:

uv run python procedural_microorganisms.py \ 
	--out stimuli_factorial \
	--mode factorial \
	--seed 1234 \
	--shape-levels 4 \
	--appendage-levels 3 \
	--texture-levels 4 \
	--colour-levels 4 \
	--exemplars-per-cell 2 \
	--png \
	--contact-sheet

Use --overwrite when regenerating into an existing output directory.

Level Selection

The --shape-levels, --appendage-levels, --texture-levels, and --colour-levels flags accept either:

• An integer limit. --shape-levels 4 selects levels 0 through 3.
• A quoted JSON list of zero-based indices. --shape-levels "[2,4,10,11]" selects only those shape levels.

Lists must be non-empty, unique, and valid for the selected catalogue. Quote the square-bracket syntax in zsh so it is passed to the generator unchanged.

For example, this produces all combinations of four selected shapes, the no-appendage and clubbed conditions, two textures, and two colours:

uv run python procedural_microorganisms.py \
	--out selected_levels \
	--mode factorial \
	--seed 1234 \
	--shape-levels "[2,4,10,11]" \
	--appendage-levels "[0,4]" \
	--texture-levels "[0,3]" \
	--colour-levels "[1,5]" \
	--png

Current Catalogues

Dimension	Level	Name
Shape	0-11	round, oval, tri_lobed, quad_lobed, penta_lobed, hexa_lobed, hepta_lobed, octa_lobed, amoeba_a, amoeba_b, teardrop, irregular_star
Appendage	0-6	none, straight, curved_clockwise, curved_counterclockwise, clubbed, forked, short_thick
Texture	0-4	smooth, spots, stripes, waves, cells
Colour	0-7	coral, amber, lime, green, cyan, blue, violet, magenta

--exemplars-per-cell controls within-cell variants. Exemplar 0 uses the catalogue values directly. Higher exemplar indices receive deterministic jitter based on the master seed, including body rotation, appendage dimensions and curvature, and texture properties.

Main Flags

Flag	Purpose
--out PATH	Required output dataset directory.
--mode random|factorial	Random draws or all selected combinations.
--n N	Number of stimuli in random mode; default 48.
--seed N	Master seed; repeat it to reproduce the same dataset.
--exemplars-per-cell N	Number of within-combination variants.
--size N	Square canvas size in pixels; minimum 128, default 512.
--points N	Body contour samples; minimum 120, default 720.
--margin F	Minimum canvas margin fraction in [0, 0.25).
--background VALUE	transparent, CSS colour name, or hex colour.
--png	Rasterise each SVG to PNG using CairoSVG.
--contact-sheet	Write contact_sheet.jpg; requires --png.
--contact-tile N	Preview contact-sheet tile size; default 180.
--contact-columns N	Preview contact-sheet columns; default 6.
--contact-max N	Maximum preview items; default 72.
--overwrite	Permit a non-empty output directory.
--quiet	Suppress per-stimulus progress messages.

Run the following for the complete command-line reference:

uv run python procedural_microorganisms.py --help

Parameter Contact Sheet

parameter_contact_sheet.py generates a single PNG intended for visual inspection of the catalogue. It invokes the generator in temporary directories, then creates a four-row contact sheet:

• Each row varies one parameter: shape, appendage, texture, or colour.
• Each column is one current level for that parameter.
• Labels are read from generated metadata, so they follow the catalogue names.
• The other three dimensions are held at level 0 in each row.

Generate the default sheet:

uv run python parameter_contact_sheet.py \
	--out parameter_contact_sheet.png

Use smaller images for a faster draft, or change the contact-sheet tile size:

uv run python parameter_contact_sheet.py \
	--out preview.png \
	--size 256 \
	--tile-size 120 \
	--seed 1234

Global Appearance Controls

The top of procedural_microorganisms.py contains several module-level constants for visual tuning. Edit these before generating a dataset:

Constant	Effect
CLUBBED_APPENDAGE_TIP_SCALE	End-club diameter relative to appendage width.
FORKED_APPENDAGE_BRANCH_LENGTH_SCALE	Forked terminal-branch length relative to appendage width.
CURVED_APPENDAGE_CURVATURE	Shared curvature magnitude for the clockwise and counterclockwise variants.
EXEMPLAR_BODY_ROTATION_JITTER_DEG	Maximum random exemplar body rotation; sampled from $[-X, X]$ degrees.
COLOUR_GRADIENT_LIGHTNESS_DELTA_SCALE	Strength of the body gradient lightness difference.
COLOUR_GRADIENT_TYPE	Set to "linear" or "radial".
SHAPE_CONTOUR_EXAGGERATION	Harmonic-amplitude multiplier; higher values exaggerate lobes while body area remains normalized.

Output Layout

For --out stimuli_random, the generator writes:

stimuli_random/
	README.md
	metadata.json
	metadata.csv
	contact_sheet.jpg             # Only with --png --contact-sheet
	svg/                          # Editable vector stimuli
	png/                          # Only with --png
	masks/
		body/                       # Body-only binary masks
		object/                     # Body plus appendages binary masks

metadata.json contains the full generator settings and nested parameter specification for every stimulus. metadata.csv provides analysis-friendly flattened records, including geometry and pixel measurements. Treat the metadata as the source of truth for stimulus identity rather than inferring conditions from filenames.

Included Sample Dataset

microorganism_samples/ is a ready-to-inspect reference dataset containing 24 random stimuli at 512 x 512 pixels, generated with seed 20260718. It uses the full current catalogues: 12 shapes, 7 appendage conditions, 5 textures, and 8 colours. It includes SVGs, PNGs, body and whole-object masks, a JSON manifest, a flat metadata table, and contact_sheet.jpg.

Start with these files:

• microorganism_samples/README.md for its generation summary.
• microorganism_samples/contact_sheet.jpg for a visual overview.
• microorganism_samples/metadata.json for full per-stimulus specifications.
• microorganism_samples/metadata.csv for a flat analysis table.
• microorganism_samples/png/ for rendered images.
• microorganism_samples/masks/body/ and microorganism_samples/masks/object/ for masks.

The sample's retained quality_control.csv is a legacy duplicate of metadata.csv; newly generated datasets only create metadata.csv.

Shape Area Matching

Body contours are area-normalized after their radial-Fourier shape parameters are applied. To verify this, all 12 shape levels were measured at the default 512 x 512 canvas with appendage level 0 (none):

• Vector body area: every shape measured 62,280.94 px²; the observed range was effectively 0.0 px² (0.00%).
• Raster body-mask area: the mean was 62,689.917 pixels, with a minimum of 62,668 (teardrop) and maximum of 62,721 (penta_lobed). The 53-pixel range is approximately 0.0845% of the mean.

The small raster difference comes from converting different vector boundaries to whole pixels. The underlying vector areas are matched; changing SHAPE_CONTOUR_EXAGGERATION still preserves this normalization.

Experimental Note

The palette uses nominal CIELCh lightness and should be treated as approximately isoluminant only. For behavioural experiments, calibrate the actual display and validate discriminability and interference properties for the intended task.

Related Stimulus Sets And Reading

These articles provide useful background on established artificial object sets and approaches to controlled visual-stimulus design. They also have cool names!

1. Wong, A. C.-N., Palmeri, T. J., & Gauthier, I. (2009). Conditions for facelike expertise with objects: Becoming a Ziggerin expert--but which type? Psychological Science, 20(9), 1108-1117. https://doi.org/10.1111/j.1467-9280.2009.02430.x PMID: 19694980

2. Barry, T. J., Griffith, J. W., De Rossi, S., & Hermans, D. (2014). Meet the Fribbles: Novel stimuli for use within behavioural research. Frontiers in Psychology, 5, 103. https://doi.org/10.3389/fpsyg.2014.00103 PMID: 24575075

3. Apostel, A., & Rose, J. (2022). RUBubbles as a novel tool to study categorization learning. Behavior Research Methods, 54(4), 1778-1793. https://doi.org/10.3758/s13428-021-01695-2 PMID: 34671917

4. Wen, X., Malchin, L., & Womelsdorf, T. (2025). A toolbox for generating multidimensional 3D objects with fine-controlled feature space: Quaddle 2.0. Behavior Research Methods, 57(8), 219. https://doi.org/10.3758/s13428-025-02736-w PMID: 40610642

5. Miyashita Y, Higuchi S-I, Sakai K, Masui N. (1991). Generation of fractal patterns for probing the visual memory. Neurosci Res. 12: 307-311. https://doi.org/10.1016/0168-0102(91)90121-e