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
.. autoclass:: bluelake.steering.PointXY
   :no-members:
   :no-inherited-members:
.. autoclass:: bluelake.steering.MotionLimits
   :no-members:
   :no-inherited-members:
.. autoclass:: bluelake.MCLSmoothMotion

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
.. autoclass:: bluelake.steering.PointZ
   :no-members:
   :no-inherited-members:

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
.. autoclass:: bluelake.steering.PointXYZ
   :no-members:
   :no-inherited-members:

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
    bl.power.bright_field_led = 50
    print(bl.power.bright_field_led)


Camera
------

.. autoclass:: bluelake.Camera

.. autoclass:: bluelake.Sensor

.. autoclass:: bluelake.Tracker

.. autoclass:: bluelake.Template

.. autoclass:: bluelake.Background

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

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

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

.. autoclass:: bluelake.Image
   :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


Excitation
----------

For systems that feature an excitation module, a ``bluelake.excitation`` object is available which allows control over lasers of various wavelengths::

    import bluelake as bl

    # To turn on a laser
    bl.excitation.red_laser.set_powered_on(True)

    # To turn on a laser and wait for it to warm up
    bl.excitation.red_laser.set_powered_on(True, wait_for_warmup=True)

    # To set a power level
    bl.excitation.red_laser.power_level = 75

    # To manipulate a laser shutter
    bl.excitation.red_laser.shutter.open()
    bl.excitation.red_laser.shutter.close()

    # To manipulate a laser shutter without waiting for confirmation that shutter is in desired state
    bl.excitation.red_laser.shutter.open(wait_for_confirmation=False)
    bl.excitation.red_laser.shutter.close(wait_for_confirmation=False)

    # Depending on your C-Trap's build configuration, the following excitation lasers can as well be accessed:
    bl.excitation.green_laser
    bl.excitation.blue_laser
    bl.excitation.violet_laser

.. autoclass:: bluelake.excitation.ExcitationLaser
.. autoclass:: bluelake.excitation::ExcitationLaser.Shutter

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

Digital Outputs
---------------

Interface to control digital output lines of the C-Trap data acquisition (DAQ) platform. Useful for integration with other instruments::

    import bluelake as bl

    print(bl.daq.digital_output.keys())  # list all the available digital outputs

    do = bl.daq.digital_outputs["digital_output_name"]
    do.set_high()
    bl.pause(1)  # set the output high for one second
    do.set_low()

.. warning::
    Please contact LUMICKS customer support before using this feature to make sure that the selected digital output is available and does not interfere with the instrument's normal operation.

.. autoclass:: bluelake.DAQ
.. autoclass:: bluelake.DO

Active Trap Stabilization (ATS)
-------------------------------

Interface to control the ATS feature (if available on the system).

.. autoclass:: bluelake.ATS

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