Skip to content

Microtubules

Microtubule Generation

The MicrotubuleGenerator class simulates microtubule structures within a defined 3D volume. The generation process is based on creating smooth, non-intersecting centerlines for each microtubule and then populating the cylindrical surface around these centerlines with points.

Core Concepts

The simulation follows these main steps for each microtubule:

  1. Centerline Generation: A smooth B-spline curve is created to serve as the central axis of the microtubule.
  2. Collision Handling: The centerline is checked for collisions with previously generated microtubules. If a collision is detected, the curve is iteratively adjusted until it is collision-free.
  3. Surface Point Generation: Points are randomly distributed on the cylindrical surface defined by the centerline and a given tube radius.
  4. Post-processing: Optional localization noise and background noise are added to the final point cloud.

1. Centerline Generation

The foundation of each microtubule is its centerline, which is generated as a B-spline curve defined by a set of control points.

a. Control Point Generation

  • Number of Points: A random number of control points is chosen from a user-defined range (control_points_range).
  • Placement Strategy:
  • The start and end points can be generated on the boundaries of the simulation volume (generate_on_boundary: true) or anywhere within it.
  • Three generation_mode options control how boundary points are placed:
    • random: Start and end points are placed on any of the four XY faces.
    • center: The start and end points are placed on opposite faces (e.g., start on x=0, end on x=max).
    • corner: All tubes in a generation run originate from the same corner of the volume (e.g., one face on the X-axis and one on the Y-axis). This promotes parallel alignment.
  • Internal control points (if any) are always generated freely within the volume.
  • Validation: The geometry of the control points is validated to prevent unrealistic shapes. This includes checks for:
  • Minimum distance between consecutive points (min_control_point_distance).
  • Minimum angle formed by any three consecutive points (min_control_point_angle), preventing sharp turns.

b. B-Spline Fitting

  • A B-spline curve is fitted to the validated control points using scipy.interpolate.splprep.
  • The smoothness (smoothness) and degree (spline_degree) of the spline can be configured.

c. Uniform Sampling

  • The B-spline is sampled at a high resolution to approximate its true arc length.
  • Based on the desired centerline_point_spacing, a new set of uniformly spaced points is calculated along the curve's length. This ensures that the final centerline has a consistent density, regardless of the curve's shape.

2. Collision Detection and Resolution

To create a realistic simulation, microtubules should not intersect. Collision handling ensures this.

a. Voxel Grid

  • A VoxelGrid is used for efficient collision detection. The simulation volume is divided into a grid of voxels.
  • When a microtubule is successfully generated, the voxels occupied by its centerline (expanded by a collision_radius) are marked as occupied.

b. Iterative Adjustment

  • Before a new microtubule is accepted, its centerline is checked against the VoxelGrid.
  • If any part of the centerline falls into an occupied voxel, a collision is detected.
  • The algorithm then attempts to resolve the collision by adjusting the control points of the spline:
    1. A "repulsion vector" is calculated for each colliding point on the centerline, pushing it away from the existing structure.
    2. This repulsion force is distributed among all control points based on their proximity to the collision site (inverse-square distance influence).
    3. The control points are moved along the calculated adjustment vectors.
    4. A new spline and centerline are generated from the adjusted control points.
  • This process is repeated up to max_adjustment_attempts. An adaptive step size is used to make both large and fine adjustments, increasing the chance of finding a valid, collision-free path.

3. Surface Point Generation

Once a valid, collision-free centerline is established, points are generated on the microtubule's surface.

  • Density: The number of points to generate is determined by the total arc length of the centerline and the surface_points_per_sample density parameter.
  • Distribution:
  • Points are distributed randomly along the length of the centerline.
  • For each point along the centerline, a random angle (theta) is chosen. The final 3D point is placed on a circle of radius tube_radius around the centerline point, in a plane perpendicular to the centerline's tangent at that point.
  • Surface Jitter: Optionally (add_surface_jitter: true), a small amount of Gaussian noise can be added to each point's position along the tangent direction, simulating imperfections on the tube surface.
  • Clipping: All generated surface points are clipped to the padded simulation volume.

4. Post-processing

After all microtubules are generated, final optional effects are applied to the entire point cloud.

a. Localization Noise

  • If add_localization_noise: true, Gaussian noise is added to the X, Y, and Z coordinates of each point.
  • The standard deviation of this noise is controlled by localization_precision, which can be a single value for isotropic noise or a 3-element array for anisotropic noise. This simulates the inherent uncertainty in single-molecule localization microscopy (SMLM).

b. Background Noise

  • If add_background_noise: true, random points are scattered throughout the simulation volume.
  • The number of background points is determined by the volume size and the background_noise_density. These points are assigned an instance ID of 0.

c. Final Clipping

  • A final check ensures all points (including those with added noise) are within the volume defined by volume_dims and padding. Any points outside this volume are discarded.