API Reference
=============

Mirror control
--------------

Control over mirrors is provided through the `Mirror` class. Instances of this class are available by default as::

    import bluelake as bl

    bl.mirror1.move_to(x=1, y=2)

    # Note: this line will fail on dual-trap systems:
    bl.mirror3.move_to(x=0, y=0)

    # Additional mirrors are defined in bluelake:
    # (depending on actual availability of the hardware on your C-Trap)
    bl.mirror4
    bl.mirror12
    bl.mirror34

.. autoclass:: bluelake.Mirror

Telescope control
-----------------

Control over telescopes is provided through the `Telescope` class. Instances of this class are available by default as::

    import bluelake as bl

    bl.telescope12.move_to(z=1)

    # Additional telescopes are defined in bluelake:
    # (depending on actual availability of the hardware on your C-Trap)
    bl.telescope34

.. autoclass:: bluelake.Telescope

Nanostage control
-----------------

Control of the nanostage is provided through the `Nanostage` class. An instance of this class is available by default as::

    # (depending on actual availability of the hardware on your C-Trap)
    import bluelake as bl

    bl.nanostage.move_to(x=1, x=2, x=3)

.. autoclass:: bluelake.Nanostage

Shutter control
---------------

Control of the shutters is provided through the `Shutters` class. An instance of it is available as::

    import bluelake as bl

    bl.shutters.clear(1, 2, delay_ms=100)

.. autoclass:: bluelake.Shutters


Stage control
-------------

Navigation within the flow cell is done through ``bluelake.microstage``, an instance of the `Microstage` class::

    import bluelake as bl

    bl.microstage.move_to('My favorite point')

.. autoclass:: bluelake.Microstage


Fluidics control
----------------

``bluelake.fluidics`` can be used to control the microfluidics channel valves and pressure::

    import bluelake as bl

    bl.fluidics.open(1, 2, 3, 6)
    bl.fluidics.increase_pressure()
    bl.fluidics.stop_flow()

.. autoclass:: bluelake.Fluidics


Power control
-------------

Power settings can be changed through the following objects that are defined in the ``bluelake`` module::

    import bluelake as bl

    # Trapping laser
    print(bl.power.trapping_laser)  # power in %
    bl.power.trapping_laser = 50    # set to 50% power

    # Power modulation (availability varies per system)
    print(bl.power.overall_trapping_power)
    print(bl.power.qtrap_split)
    print(bl.power.trap1_split)

    # Bright-field LED
    print(bl.power.bright_field_led)

    # Excitation lasers (only for confocal systems)
    print(bl.excitation_lasers.red)
    print(bl.excitation_lasers.green)
    print(bl.excitation_lasers.blue)


Camera
------

.. autoclass:: bluelake.Camera

.. autoclass:: bluelake.Sensor

.. autoclass:: bluelake.Size
   :no-members:
   :no-inherited-members:

.. autoclass:: bluelake.Region
   :no-members:
   :no-inherited-members:

.. autoclass:: bluelake.Bounds
   :no-members:
   :no-inherited-members:


Timeline
--------

Access to data from the timeline is provided through the ``bluelake.timeline`` object, an instance of the `Timeline` class described below.

Index `timeline` to gain access to individual channels::

    import bluelake as bl

    force_channel = bl.timeline["Force HF"]["Force 1x"]

The first index is the name of a channel group; the second index is the name of a channel within the group. Group and channel names match the ones displayed in the Bluelake user interface.

The above code snippet sets the ``force_channel`` variable to an instance of the `Channel` class described below. We can now, for instance, check the latest force value that has been measured using::

    print(force_channel.latest_value)


.. autoclass:: bluelake.Timeline

.. autoclass:: bluelake.Group

.. autoclass:: bluelake.Channel

.. autoclass:: bluelake.Spec

Confocal
--------

For C-Trap systems that feature a confocal scanner, a ``bluelake.confocal`` object is available. Through this instance of the `Scanner` class described below, simple automation of confocal scans can be done.

.. py:module:: confocal

.. autoclass:: bluelake.Scanner


Focus Lock
----------

For systems that have focus lock, a ``bluelake.focus_lock`` object is available, which allows start/stopping it and checking its state.

.. autoclass:: bluelake.FocusLock

Force feedback
--------------

Force feedback is responsible for keeping the selected force stable at certain target value by using a PID loop to correct the position of steering device. Trap 1 should be used to achieve the best performance::

    import bluelake as bl

    try:
        bl.force_feedback.set_device("1")
        bl.force_feedback.set_detector("Trap 2") # Force detector
        bl.force_feedback.set_target(30)
        bl.force_feedback.enabled = True
        bl.pause(1)
    finally:
        bl.force_feedback.enabled = False

.. autoclass:: bluelake.ForceFeedback

Miscellaneous
-------------

.. autofunction:: bluelake.pause

.. function:: reset_force

    Set forces to zero. Calibrate force offsets for all channels to zero force.

.. autofunction:: bluelake.get_force_calibration
.. autoclass:: bluelake.PiezoTracker
.. autoclass:: bluelake.Calibration