# Cooled Thermal Cameras Calibration Manual
This manual describes how to work with the calibration tool (ctdcalib) used to calibrate cooled thermal cameras. The tool is a console app that can be started like:
"python3 ctdcalib.py <recipe-file> <work-folder>"

The work-folder parameter is a directory on the system where the tool will log store all its logs. The recipe file is actualy calibration procedure that the user desires to execute. The recipe is in python, but has some specific rules that need to be followed in order to write a valid recipe.
By default the tool will print its output on the stdout(console), while also saving it in a file called log.txt in the root of the work-folder.

## Recipe Creation
The recipe is a python script file, that has to conform to the following rules:
1. The recipe file cannot import any external modules
2. The recipe cannot call the exec builtin function

## Global Variables
The tool "injects" these global variables in the recipe's context, so that they are always present whenever a recipe is being executed.

| Name | Variable Purpose | 
| SESSION_DIR | a variable containing the path to the work-dir |

## Global Functions
In addition to the builtin python functions, the following functions are available in the global scope of the recipe:

| Name | Function |
| LOG  | a logging function that writes to the log file for the current session | 

## Controllable Devices
All controllable devices support the following functions:
* open()
    - definition: establishes the connection with the device, after which point all functions are usable. If the device is not open, then you cannot use any of its other features
    - parameters: None
    - returns: None
* close()
    - definition: closes the connection with an open device, preventing any futher commands to it from being executed
    - parameters: None
    - returns: None

Each device type has a specific type that is provided by the tool, that the recipe can utilize.

!NOTE: The constructor of each device type automatically calls open on the device

### Black Body
#### Supported functions
* set_abs_temperature(temp:float)
    - definition: starts the device in absolute mode, in which an absolute temperature of the emitter is maintained, regardless of the background temperature
    - parameters:
        * temp -  the desired absolute temperature
    - returns: None
* set_diff_temperature(temp:float)
    - definition: starts the device in differential mode, in which the temperature of the emitter is calculated based on the difference with the background temp
    - parameters:
        * temp -  the differential temp, in Celcium. If temp=10 and the background temperature is 20, then the emitter temperature target will be 30.
    - returns: None
* stop_emitter()
    - definition: exits any started mode and reverts to standby state. In this state the black body does not maintain any specific temperature of the emitter and the emitter will slowly reach the background temp (because it is OFF).
    - parameters: None
    - returns: None
* get_emiter_temperature()
   - definition: gets the current emiter temperature
    - parameters: None
    - returns: float, current temperature  in degress Celcium
* get_background_temperature()
   - definition: gets the current background temperature
    - parameters: None
    - returns: float, current temperature in degress Celcium

### Bidentifier Mwir
This device is a camera with a single thermal sensor, it requires a network connection. The camera supports a 100 valid NUC slots (0-99). The 100th slot is reserved for using 1pnuc, the 101 slot is reserved for the default buffers. The 1pnuc and default slot are not memory mapped, while the 0-99 nuc range are stored in flash. The device first needs to load them to RAM(done automatically on device startup) to use them and if the user wants to save any changes made to them, they need to be saved to back to flash.
#### Constructor
BidentifierMwir(ip, username, password)
- ip: the network address of the device, accessible from the calibration machine
- username: login username for ssh connection
- pass: the password for ssh connection

#### Supported functions
* one_point_nuc()
    - definition: creates a 1pnuc from the gain of the currently selected slot, the result is placed in the 1pnuc slot
    - parameters: no parameters
    - returns: None
* one_point_nuc_defocus()
    - definition: creates a 1pnuc from the gain of the currently selected slot, the result is placed in the 1pnuc slot. Before the actual nuc procedure is executed, the camera defocuses, then after the procedure is complete it returns to its previous location
    - parameters: no parameters
    - returns: None
* set_nuc(slot:int)
    - definition: use the specified slot as NUC
    - parameters
        * slot - the desired NUC slot, 0-101 is the valid range
    - returns: None
* save_nuc(slot:int)
    - definition: save 2pNUC slot from RAM -> FLASH
    - parameters
        * slot - the desired NUC slot, 0-99 is the valid range
    - returns: None
* restore_nuc(slot_int):
    - definition:restore 2pNUC slot from FLASH -> RAM
    - parameters
        * slot - the desired NUC slot, 0-99 is the valid range
    - returns: None
* two_point_nuc_low()
    - definition: performs a 2pnuc-low operation
    - parameters : None
    - returns: None
* two_point_nuc_high()
    - definition: performs a 2pnuc-high operation
    - parameters : None
    - returns: None
* two_point_nuc_calc()
    - definition: performs a 2pnuc-calc operation
    - parameters : None
    - returns: None
* download_nuc_raw(low_path:str, high_path:str)
    - definition: downloads the raw input parts that were taken by the last "calc low" and "calc high" commands
    - parameters :
        * low_path - path on the filesystem where to save the low raw file
        * high_path - path on the filesystem where to save the high raw file
    - returns: None
* download_raw(path:str)
    - definition: downloads a raw image from the camera
    - parameters :
        * path - path on the filesystem where to save the  raw file
    - returns: None
* download_nbc(path:str)
    - definition: downloads a raw image from the camera, after NUC and BPC
    - parameters :
        * path - path on the filesystem where to save the  raw file
    - returns: None
* download_nuc(path:str, slot:int)
    - definition: downloads a NUC from the specified slot
    - parameters :
        * path - path on the filesystem where to save the NUC file
        * slot - the desired NUC slot, 0-101 is the valid range
    - returns: None
* upload_nuc(path:str, slot:int)
    - definition: downloads a NUC from the specified slot
    - parameters :
        * path - path on the filesystem where to read the NUC file
        * slot - the desired NUC slot, 0-101 is the valid range
    - returns: None
* copy_nuc(src_slot:int, dst_slot:int)
    - definition: copies a NUC from one slot to another (only in RAM)
    - parameters :
        * src_slot - NUC slot to read from, 0-101 is the valid range
        * dst_slot - NUC slot to save to, 0-101 is the valid range
    - returns: None

* download_all() #TODO
* upload_all() #TODO
* save_all() #TODO
* restore_all() #TODO

* set_fov(fov:int)
    - definition: Move the lens to a predefined field-of-view(FOV). This command blocks until the move is complete.
    - parameters:
        * fov - 1 - WFOV, 2 - MFOV, 3 - NFOV, valid range [0-2]
    - returns: None
* get_lens_position()
    - definition: Read the current position of the lens driver
    - parameters: None
    - returns: a dictionary with the following keys
        * zoom - unsigned 16-bit position
        * focus - unsigned 16-bit position
        * temperature - in degrees celcium
        * bit - BIT result byte
        * work-hours - 
        * busy
        * zoom-absolue
        * focus-absolute
* set_zoom_position(pos:int)
    - definition: sets the zoom position of the lens driver
    - parameters: 
        * pos - int, the desired zoom position, unsigned 16-bit
    - returns: None
* set_focus_position(pos:int)
    - definition: sets the focus position of the lens driver
    - parameters: 
        * pos - int, the desired focus position, unsigned 16-bit
    - returns: None
* get_image_processing_status()
    - definition: returns the image processing status of the camera. These are based on configuration + current scene.
    - returns: a dictionary with the following keys
        * tail-rejection-low
        * tail-rejection-high
        * agl-low
        * agl-high
        * histogram-low
        * histogram- high
        * average
        * offset
        * digital-zoom -- float, coefficient from x1 to x8
        * current-nuc -- int, from 0 to 101

* get_sensor_id()
    - definition: returns the sensor's id number
    - parameters: 
    - returns: string
* set_integration_time(it:int)
    - definition: sets the camera integration time
    - parameters
        * it - sets the current integration time, in uS
    - returns: None
* get_integration_time()
    - definition: gets the current integration time
    - parameters: None
    - returns: int, the integration time in uS
* set_fps(fps:int)
    - definition: sets the camera fps
    - parameters
        * fps - sets the current fps
    - returns: None
* get_fps()
    - definition: gets the current fps
    - parameters: None
    - returns: int

### Climate Chamber
This a device can accurately set the temperature itside its enclosure. 
#### Constructor
ClimateChamber(ip:str, port:int)

#### Supported functions
* set_temperature(temp:float)
    - definition: sets the temperature of the chamber
    - parameters:
        - temp: float, in degrees Celcium
    - returns: None
* set_humidity(hum:float)
    - definition: sets the humidity of the chamber
    - parameters:
        - hum: float, the humidity from 0 to 100% in relative %
    - returns: None
* get_status() 
    - definition:gets the current chamber status
    - parameters: None
    - returns: dictionary, with keys "temperature and "humidity"
* get_device_info()
    - definition: gets the device information
    - parameters: None
    - returns: dictionary, with keys "server-version", "serial-number" and "system-type"

### Motor Rail
This is a serially connected device that can accurately position a "thumb" located on a motorized rail. The thumb allows for several other devices to be mounted on it - and thus positioned precisely on the rail.

#### Constructor
MotorRail(port:int)
- port - the serial port on which to locate the device

#### Supported functions
* get_pos()
* get_device_info()
    - definition: gets the device information
    - parameters: None
    - returns: dictionary, with keys "server-version", "serial-number" and "system-type"
* set_pos() #TODO
* reset_position() #TODO

