pylabrobot.lib.liquid_handling.channel_positioning.compute_channel_offsets#

pylabrobot.lib.liquid_handling.channel_positioning.compute_channel_offsets(resource: Resource, num_channels: int, spread: str = 'wide', channel_spacings: List[float] | None = None) → List[Coordinate]#

Compute Y offsets for positioning consecutive channels (0..num_channels-1) in a resource.

Handles container geometry: compartments with no-go zones, wide/tight spread. Assumes channels are consecutively indexed — for non-consecutive channel selections (e.g. [0, 2, 5]), use compute_nonconsecutive_channel_offsets instead.

Parameters:

  • resource (Resource) – The target resource (Container, Trough, Well, etc.).

  • num_channels (int) – Number of channels to position.

  • spread (str) – Positioning strategy: - “wide”: spread channels as far apart as possible (respects no-go zones if present) - “tight”: pack channels at minimum spacing (respects no-go zones if present) - “custom”: return zero offsets (caller controls positioning)

  • channel_spacings (List[float] | None) – Per-channel occupancy diameters in mm (length = num_channels). Each value is the physical space the channel occupies. The required gap between channels i and i+1 = spacing[i]/2 + spacing[i+1]/2 (sum of radii). If None, defaults to 9mm for all channels.

Returns:

List of Y offsets relative to the resource center, sorted back-to-front (descending Y).

Raises:

  • ChannelsDoNotFitError – If channels cannot fit within the resource’s compartments.

  • ValueError – If spread is not “wide”, “tight”, or “custom”.

Return type:

List[Coordinate]