owl.instruments.Illuminate

class owl.instruments.Illuminate(*, N_cameras_Y=None, N_cameras_X=None, flip_along_y=False, flip_along_x=False, check_version=True, **kwargs)

Bases: IlluminateTools, Illuminate

static update_firmware(serial_number, *, device_name=None, mcu=None)

Update a device firmware.

Update the device firmware by specifying its serial number.

For unregistered devices, one can specify the device_name manually.

Parameters:

• serial_number (str) – The serial number of the device to open.

• device_name (str) – Optional parameter to specify exactly what firmware to program on the device.

• mcu (None or 'TEENSY31') – The microcontroller unit used in the LED board. If device_name is not specified, this parameter is ignored.

static list_all_serial_numbers(serial_numbers=None)

Find all the currently connected Illuminate serial numbers.

Parameters:

serial_numbers (list of str, or None) – If provided, will only match the serial numbers that are contained in the provided list.

Returns:

serial_numbers – List of connected serial numbers.

Return type:

list of serial numbers

Note

If a list of serial numbers is not provided, then this function may match Teensy 3.1/3.2 microcontrollers that are connected to the computer but that may not be associated with the Illuminate boards.

classmethod by_device_name(device_name, *args, **kwargs)

Connect to an LED board by device name.

property NA: float

Numerical aperture for bf / df / dpc / cdpc patterns.

property about: str

Display information about this LED Array.

property analog_brightness_settings

Electrical current settings for the LEDs.

The analog brightness settings are only valid for Illuminate boards that have the necessary hardware. As of today, only the c-008-falcon-transmission board supports analog current control through the use of special features in the TLC5955 [1].

In the parameter definition below, MC refers to the maximum current setting, BC refers to the brightness control setting, and DC refers to the dot correction setting.

The settings are expected to be organized as a tuple of length 3. Each tuple should contain either a tuple of 3 integers or a single integer.

>>> light.analog_brightness_settings = ((MC_R, MC_G, MC_B),
...                                     (BC_R, BC_G, BC_B),
...                                     (DC_R, DC_G, DC_B))

Notes

Setting MC, BC, and DC to 0 will not turn that LED channel off.

_[1] https://www.ti.com/lit/ds/symlink/tlc5955.pdf

annulus(minNA: float, maxNA: float) → None

Display annulus pattern set by min/max NA.

property array_distance: float

LED array distance in meters.

ask(data: str) → int | float | None

Send data, read the output, check for error, extract a number.

property autoclear: bool

Toggle clearing of array between led updates.

Returns:

value – The current setting of autoclear

Return type:

bool

property autoupdate: bool

Toggle updating of array between led commands.

Returns:

value – The current setting of autoupdate

Return type:

bool

property background_color

The background RGB color set when the IR leds are on.

Only valid in ‘ir850_analog_fullarray’ is used.

The color of the RGB leds.

property background_lux

The target brightness (in Lux) of the RGB leds.

Only valid when ‘ir850_analog_fullarray’ is used.

brightfield() → None

Display brightfield pattern.

property channel_current

The analog current output of each channel.

This function helps estimate the average analog current provided to each LED given the present analog and grayscale (pulse width modulation or PWM for short) settings for the LED Board.

For example, the C008-Transmission (based on the TCL5955 controller) can output a current between 0.08384 mA to 31.9 mA when PWM is disabled.

The analog current can not be set to 0 unless the PWM settings are also set to 0.

Examples

Demonstrating the need to set color value to 0 first in order to set current to 0 >>> light = Illuminate() # It is best to change the analog settings when the PWM is set to 0 >>> light.color = 0 >>> light.analog_brightness_settings = (0, 0, 0) >>> light.color = (255, 255, 0) >>> print(light.channel_current) (8.384E-5, 8.384E-5, 0.0)

To set the output current to 0, the PWM settings must be set to zero. >>> light.color = 0 >>> print(light.channel_current) (0.0, 0.0, 0.0)

Set brightness based on expected color ratio and brightness >>> color_ratio = (0.813, 0.168, 0.557) >>> brightness_percentage = 0.1 >>> light.color = (255, 255, 255) >>> max_current = light.get_maximum_channel_current() >>> channel_current = tuple(m * c * brightness_percentage … for m, c in zip(max_current, color_ratio)) >>> light.channel_current = channel_current >>> light.fill_array() >>> print(light.channel_current) (0.000678, 0.000143, 0.000464)

clear() → None

Clear the LED array.

close() → None

Force close the serial port.

property color: Tuple[float, ...]

LED array color.

Returns a tuple for the (red, green, blue) value of the LEDs.

Returns:

• red – Integer value for the brightness of the red pixel.

• green – Integer value for the brightness of the green pixel.

• blue – Integer value for the blue pixels.

property color_maximum_value

Maximum color intensity that can provided to the LED board.

property color_minimum_increment

Minium intensity increment that can be provided to the LED board.

darkfield() → None

Display darkfield pattern.

debug(value=None)

Set a debug flag. Toggles if value is None.

delay(t)

Simply puts the device in a loop for the amount of time in seconds.

Prints newline approximately 100 ms.

Returns:

None

demo(time: float = 10) → None

Run a demo routine to show what the array can do.

Ok, I don’t know what that blinking is doing, when it is blinking, it won’t respond to serial commands. Therefore, if you try to wake it up while it is blinking, it simply will ignore you

SEems to blink for a while before starting. Maybe it is turning on some UV leds on my board? So this demo’s default time is set to 20 instead.

property device_info

Provide the serial number and other device info in a dictionary.

The returned dictionary contains the following keys: ['serial_number', 'device_name']

property device_name

The human readable name of the device.

discoparty_demo(n_leds=1, time=10)

Run a demo routine to show what the array can do.

Parameters:

• n_led – Number of LEDs to turn on at once

• time – The amount of time to run the paterns in seconds

draw_channel(led)

Draw LED by hardware channel(use for debugging).

draw_circle(Y_index, X_index, radius=1, set_leds=True, led_type='rgb')

Illuminate the LEDs in a circle centered at a given index.

Units provided are in “microcamera” units, where 1 camera corresponds to the pitch between microcameras.

For the Falcon Illumination units, this is 13.5 mm.

Parameters:

• Y_index (int) – Y coordinate of the center of the circle.

• X_index (int) – X coordinate of the center of the circle.

• radius (float) – Radius of the circle.

• set_leds (bool) – If set to False, this will just return the LEDs without sending them to the LED board so they can be used in sequences

• led_type ('rgb', 'uv', or , 'ir', 'all') – The type of LED to turn on around the perimeter.

Returns:

leds – LEDs that correspond to the circle directly below the indicated camera index.

Return type:

List[int]

draw_edge(num_leds=4, led_type='rgb', set_leds=True)

Lights the leds on the parameter of the board.

You can be used for quick global dark field illumination to remove the reflection from reflective samples.

Currently, only the reflection illumination board is supported.

Parameters:

• num_leds (int) – The number of LEDs on the perimeter to light up.

• led_type ('rgb', 'uv', 'ir', or 'all') – The type of LED to turn on around the perimeter.

• set_leds (bool) – If set to False, this will just return a list of LEDs that would be set instead of directly changing the LED pattern on the board.

Returns:

led_list – The list of LEDs that were turned on by this function.

Return type:

List[int]

draw_grid(grid_index=0, set_leds=True)

Lights the leds on board in a grid pattern.

Currently, it is used to separate coherent and incoherent illumination in the BF illumination module. Supported only on the c012.

Parameters:

• grid_index (int) – To decide which grid pattern to be turned on.

• led_type ('rgb', 'uv', or , 'ir', 'all') – The type of LED to turn on around the perimeter.

• set_leds (bool) – If set to False, this will just return a list of LEDs that would be set instead of directly changing the LED pattern on the board.

Returns:

led_list – The list of LEDs that were turned on by this function.

Return type:

List[int]

draw_hole(Y_index, X_index, radius=1)

Illuminate LEDs around a single hole.

draw_quadrant(red: int, green: int, blue: int) → None

Draws single quadrant.

draw_square(Y_index, X_index, width=1.25, set_leds=True, led_type='rgb')

Illuminate the LEDs in a square at a given micro camera index.

Units provided are in “microcamera” units, where 1 camera corresponds to the pitch between microcameras.

For the Falcon Illumination units, this is 13.5 mm.

Parameters:

• Y_index (int) – Y coordinate of the center of the square.

• X_index (int) – X coordinate of the center of the square.

• width (float) – Width of the square.

• set_leds (bool) – If set to False, this will just return the LEDs without sending them to the LED board, so they can be used in sequences.

• led_type ('rgb', 'uv', or , 'ir', 'all') – The type of LED to turn on around the perimeter.

Returns:

leds – LEDs that correspond to the ones below the camera index.

Return type:

List[int]

fill_array(led_type='rgb')

Turn on all leds of a given type.

Parameters:

led_type ({'any', 'rgb', 'uv', 'ir'})

static find(serial_numbers=None)

Find all the serial ports that are associated with Illuminate.

Parameters:

serial_numbers (list of str, or None) – If provided, will only match the serial numbers that are contained in the provided list.

Returns:

devices – List of serial devices

Return type:

list of serial devices

Note

If a list of serial numbers is not provided, then this function may match Teensy 3.1/3.2 microcontrollers that are connected to the computer but that may not be associated with the Illuminate boards.

find_max_brightness(num_leds, color_ratio=None)

Calculate the maximum brightness for each color channel of an LED that won’t exceed the TLC’s internal current limit.

Parameters:

• num_leds (int) – The number of LEDs to be illuminated.

• color_ratio ((float, float, float)) – The required ratio for the brightness values of each color channel (r, g, b)

Returns:

brightness – The maximum scaled brightness for each color channel.

Return type:

(float, float, float)

find_nearest(y, x, led_type='rgb')

Finds the nearest LED to the given coordinate.

Parameters:

• y (float) – y coordinate in meters.

• x (float) – x coordinate in meters.

• led_type ({'any', 'rgb', 'uv', 'ir'}) – LED chromaticity to search for.

Returns:

led_index – LED index closest to the provided coordinate according to the Euclidean distance (i.e. L2-norm).

Return type:

int

find_row(led, direction='horizontal', led_type='any')

Given an LED, find the row which it belongs to.

Parameters:

• led (int)

• led_type ({'any', 'rgb', 'uv', 'ir'})

• direction ({'horizontal', 'vertical'})

Returns:

leds – List of the indices of all LEDs in the same row as the provided led.

Return type:

list

half_annulus(pattern: str, minNA: float, maxNA: float) → None

Illuminate half annulus.

half_circle(pattern: str) → None

Illuminate half circle(DPC) pattern.

Parameters:

pattern (should be 'top', 'bottom', 'left' or 'right')

half_circle_color(red: int, green: int, blue: int) → None

Illuminate color DPC pattern.

property help: str

Display help information from the illuminate board.

illuminate_uv(number: int) → None

Illuminate UV LED.

property led: List[int]

Turn on list of LEDs.

Note that the LEDs along the edges do not have all the colors. Therefore, it might be deceiving if you set the color to red, then call ` Illuminate.led = 0 ` which makes it seem like it turned off the LEDs, but in fact, it simply set LED #0 to the color red, which for that particular LED doesn’t exist.

property led_current_amps

Maximum current in amps per LED channel.

property led_positions

Position of each LED in cartesian coordinates[mm].

property led_positions_NA

Print the position of each LED in NA coordinates.

Not working: See[PR # 8](https://github.com/zfphil/illuminate/pull/8)

property led_state

Current state of the Illuminate LEDs in RGB as a DataArray.

property mac_address: str

MAC Address of the Teansy that drives the LED board.

property parameters_json

Print system parameters in a json file.

NA, LED Array z - distance, etc.

positions_as_xarray()

Return the position of the led information as an xarray.DataArray.

Returns:

led_position – This dataarray contains a Nx3 matrix that has rows with the z, y, x coordinates of the leds.

Return type:

xr.DataArray

property precision

Python interface bitdepth

print_sequence() → str

Print sequence values to the terminal.

Returns:

s – Human readable

Return type:

string

print_sequence_length()

Print sequence length to the terminal.

print_values()

Print LED value for software interface.

read(size: int = 10000) → bytearray

Read data from the serial port.

Returns:

data – bytearray of data read.

Return type:

bytearray

read_paragraph(raw=False) → List[str]

Read a whole paragraph of text.

Returns:

lines – A list of the lines in the paragraph.

Return type:

list

readline() → str

Call underlying readline and decode as utf-8.

reboot()

Run setup routine again, for resetting LED array.

reset_sequence()

Reset sequence index to start.

run_sequence(delay: float, trigger_modes: List[float]) → None

Run sequence with specified delay between each update.

If update speed is too fast, a: (is shown on the LED array.

run_sequence_fast(delay, trigger_modes)

Not implemented yet.

scan_brightfield(delay: float | None = None) → None

Scan all brightfield LEDs.

Sends trigger pulse in between images.

Outputs LED list to serial terminal.

scan_full(delay: float | None = None) → None

Scan all active LEDs.

Sends trigger pulse in between images.

Delay in seconds.

Outputs LED list to serial terminal.

property sequence: List[int]

LED sequence value.

The sequence should be a list of LEDs with their LED number.

property sequence_bit_depth

1, 8, [or 16?].

Type:

Set bit depth of sequence values

property sequence_length: int

Sequence length in terms of independent patterns.

set_brightness(brightness_fraction, illumination_mode=None, *, color_ratio=None, background_lux=0, background_color_ratio=None, wait=True)

Set the brightness for a given illumination mode and color.

Parameters:

• brightness_fraction (float) – A value from 0 to 1 that sets the illumination board to that fraction of the max possible brightness.

• illumination_mode (str) – The desired mode of illumination. If none is given will keep the currenet illumination mode.

• color_ratio (tuple of floats) – A tuple of length 3 that lists the ratio between the channels. Any values can be given, but the ratios will be normalized so that they sum to 1. This is only valid for the ‘visible’ illumination modes.

set_pin_order(red_pin, green_pin, blue_pin, led=None)

Set pin order(R / G / B) for setup purposes.

step_sequence(trigger_start, trigger_update)

Trigger sequence.

Triggers represents the trigger output from each trigger pin on the teensy. The modes can be:

0: No triggering 1: Trigger at start of frame 2: Trigger each update of pattern

trigger(index)

Output TTL trigger pulse to camera.

trigger_print()

Print information about the current i / o trigger setting.

Returns:

s – Human readable string describing the trigger.

Return type:

string

trigger_setup(index, pin_index, delay)

Set up hardware(TTL) triggering.

trigger_test(index)

Wait for trigger pulses on the defined channel.

turn_on_led(leds: int | Iterable[int]) → None

Turn on a single LED(or multiple LEDs in an iterable).

Parameters:

leds (single item or list-like) – If this is single item, then the single LED is turned on. If this is an iterable, such as a list, tuple, or numpy array, turn on all the LEDs listed in the iterable. ND numpy arrays are first converted to 1D numpy arrays, then to a list.

update() → None

Update the LED array.

property version: str

Display controller version number.

water_drop_demo(time: float = 10) → None

Water drop demo.

write(data) → None

Write data to the port.

If it is a string, encode it as ‘utf-8’.