🔬 MorphoTrack: Synthetic 2D+T Microscopy Generator

MorphoTrack is a high-fidelity synthetic data engine that generates multi-channel 3D videos ("tracks") of biological objects. By morphing between morphological archetypes using a Markov chain, it creates diverse datasets for training and validating tracking and classification algorithms.

🛠 1. Requirements & Setup

Environment

• Script: synth\_data.ipynb (or the packaged src/ modules).
• Env: DINO\_env or any Python 3.9+ environment.
• Dependencies: numpy, pandas, matplotlib, scipy, tqdm, tifffile.

Installation

1. Activate your environment.

2. Initialize Classes: If using the notebook, run all cells up to "Full Track Simulation". This loads the SyntheticImageGenerator and TrackSimulator logic.

🏗 2. The Three-Stage Pipeline

I. The Stage (SyntheticImageGenerator)

The physical engine. It handles the rendering of shapes (Square, Rectangle, Circle, Ellipse) and simulates microscopy artifacts like Poisson Noise (photon scale) and Gaussian Blur.

II. The Director (TrackSimulator)

The Markovian controller. It manages the "life story" of the object, ensuring mathematical continuity so that position, rotation, and size never "flicker" during state transitions.

III. The Factory (Post-Processing)

Directly extracts crops from the generated tracks and saves them into class-specific directories, complete with a metadata.csv compatible with UMAP_explorer.

⚙️ 3. Configuring the Simulation

The simulation behavior is controlled by the example\_config dictionary.

A. Defining States & Logic

• States: List your archetypes (e.g., ["sml_sq", "rectangle", "big_sq"]).

  • Pro-Tip: If you include "end" in your state list and transition matrix, the track will terminate early if it hits that state. If you don't use "end", the track will always run for the total_channels length defined in the execution cell.

• Initial Probability: The chance of starting in each specific state.

• Transition Matrix: Probabilities of moving from State A to State B (Rows must sum to 1.0).

• Transition Duration: Set the number of frames for a morph using a Distribution.

B. Gradient Types

Gradients define the "look" of a transition (size, intensity, position, and blur):

• linear: Constant, steady change.

• sigmoid: S-Curve (Slow → Fast → Slow). Best for organic biological morphs.

  • Param: gradient_params={'steepness': 10.0}.

• exponential: Accelerated change. Starts slow, surges at the end.

• logarithmic: Decelerated change. Rapid jump, then settles.

• cosine: Smooth, rounded easing; softer entry/exit than sigmoid.

• quadratic: Power-based easing ($t^n$).

  • Param: gradient_params={'exponent': 2.0}.
  • Use an exponent > 1.0 to "Ease In" (accelerate).
  • Use an exponent < 1.0 to "Ease Out" (decelerate).

Note: You can set a global gradient_type or override it per-property (e.g., 'size_gradient_type': 'logarithmic').

📊 4. Parameter Distribution Reference

Use these types for state properties like intensity, size, or rotation_delta:

Distribution Type	Dictionary Syntax	Description
Fixed	{"type": "fixed", "value": 300}	Constant value for every frame in state.
Uniform	{"type": "uniform", "min": 10, "max": 20}	Randomly samples within a range.
Normal	{"type": "normal", "mean": 50, "std": 5}	Samples from a bell curve.
Clipped Normal	{"type": "normal", ..., "min_clip": 0}	Normal distribution that stays within limits.

Note: For coordinates or sizes, pass lists: {"min": [y1, x1], "max": [y2, x2]}.

🚀 5. Execution Workflow

1. Generate Tracks: Run the simulation cells. You can explore built-in examples for Circle-Ellipse Morphs or the default Square-Rectangle dataset.

2. Extract Windows: Run the remaining cells under "Full Track Simulation".

   • This extracts crops and saves them as individual .tif files.

   • Labeling: Windows are classified as STATE_X, TRANSITION_A_B, or CONTAMINATED (straddling a boundary).

📁 6. Output & Metadata

The tool creates one directory per class. Inside, crops are saved as TIFs with a metadata.csv containing:

• file_path & filename

• track_id & t_start

• y_center & x_center (centroid position)

• window_size & class

Quick Summary:

1. Activate Env → 2. Run Class Definitions → 3. Configure example_config → 4. Run "Full Track Simulation".