detector_list
=============

DetectorList
++++++++++++


A description of detector positions and properties.

The list of detectors must have the following table columns
::

    id   x_cen   y_cen  x_size  y_size  pixel_size  angle    gain

where:

* "id" is a reference id for the chip (fits header EXTNAME)
* "x_cen" and "y_cen" [mm] are the physical coordinates of centre of the chip on the detector plane
* "x_size", "y_size" [mm, pixel] are the width/height of the chip
* "pixel_size" [mm] is the physical size of pixels in the detector
* "angle" [deg] is the rotation of the detector relative to the x-axis
* "gain" [e-/ADU] is the conversion factor for electrons (photons) to ADUs

The units for each column (except ``id``) must be given in the meta data
using the format ``<colname>_unit``. E.g. ``x_size_unit``.
See examples below.

.. note::
   Currently only the units specified below are accepted.

   For ``x(y)_size_unit``, acceptable units are ``mm``, ``pixel``

Parameters
----------
filename : str, optional
    Filename of the ASCII file with the detector description. See examples

array_dict : dict
    Dict containing the detector description. See examples

image_plane_id : int
    Which image plane the detector will look at (generally 0)

Examples
--------
With the ``array_dict`` feature
::

    -   name: single_detector
        class: DetectorList
        kwargs:
            image_plane_id : 0
            array_dict:
                id: [1]
                x_cen: [0.]
                y_cen: [0.]
                x_size: [5.12]
                y_size: [5.12]
                pixel_size: [0.01]
                angle: [0.]
                gain: [1.0]
            x_cen_unit: mm
            y_cen_unit: mm
            x_size_unit: mm
            y_size_unit: mm
            pixel_size_unit: mm
            angle_unit: deg
            gain_unit: electron/adu


Or referring to a table contained in a seperate ASCII file
::

    - name : full_detector_array
      class : DetectorList
      kwargs :
        filename : "detecotr_list.dat"
        active_detectors : [1, 3]
        image_plane_id : 0

where the file detector_list.dat contains the following information
::

    # x_cen_unit : mm
    # y_cen_unit : mm
    # x_size_unit : pix
    # y_size_unit : pix
    # pixel_size_unit : mm
    # angle_unit : deg
    # gain_unit : electron/adu
    #
    id   x_cen   y_cen  x_size  y_size  pixel_size  angle    gain
    1   -63.94    0.00    4096    4096       0.015    0.0     1.0
    2     0.00    0.00    4096    4096       0.015   90.0     1.0
    3    63.94    0.00    4096    4096       0.015  180.0     1.0



DetectorWindow
++++++++++++++


For when a full DetectorList if too cumbersome.

Parameters
----------
pixel_size : float
    [mm pixel-1] Physical pixel size
x, y : float
    [mm] Position of window centre relative to optical axis
width, height=None : float
    [mm] Dimensions of window. If height is None, height=width
angle : float, optional
    [deg] Rotation of window
gain : float, optional
    [ADU/e-]
units : str, optional
    [mm, pixel] Default "mm". Sets the input parameter units.
    If ``"pixel"``, (``x``, ``y``, ``width``, ``height``) are multiplied
    by ``pixel_size``