# xsptools

`xsptools` is a collection of python packages for the processing of data originating
from X-Spectrum detectors. Therefore, each package should be used in conjunction with
a library that allows access to a detector, such as `pyxsp` [1].

## Installation

`xsptools` requires:

* Python >= 3.8
* Numpy >= 1.6

The package itself can be installed with pip:

```bash
$ pip install xsptools
```

## Supported packages

The following packages are supported by `xsptools`:

* [xsptools.binning](#xsptoolsbinning)

Each package can be imported specifying its name, for example:

```python 
from xsptools import binning
```

## xsptools.binning

`xsptools.binning` is a package that is used to perform 3x3 binning of
frames generated by X-Spectrum detectors. The only supported detector at the moment
is a Lambda CdTe 750k.
The main object is the `Processor`, which is instantiated by passing the frame
dimensions:

```python
from xsptools import binning
p = binning.Processor(516,1554)
```

Its functionality is to bin frames, which must be passed as 2-dimensional
numpy arrays with the same dimensions as those passed to the `Processor`. It is
also possible to add to the `Processor` the detector pixel mask, which is used to
interpolate bad pixels (before binning, each bad pixel is set to be the
average of its neighbors). This procedure is generally recommended as it results in
better looking binned frames.
The `Processor`'s full API can be exposed via:

```python
from xsptools import binning
help(binning.Processor)
```

The following is a complete code example that shows how to use the package:

```python
from xsptools import binning
import numpy as np
import matplotlib.pyplot as plt


p = binning.Processor(frame_height=516, frame_width=1556)

# Mock pixel mask
pixel_mask = np.zeros(shape=(516,1554), dtype=np.uint32)
p.add_pixel_mask(pixel_mask)

# Mock frame
frame = np.random.randint(0, 256, size=(516,1554), dtype=np.uint8)
binned_frame = p.bin_frame(frame)

height = p.binned_frame_height
width = p.binned_frame_width
plt.imshow(binned_frame, extent=(0,width,height,0))
plt.show()
```

## Licensing

The `xsptools` package is licensed under the terms of the BSD  3-clause license 
(also known as Modified BSD License).

## References

[1] pyxsp User Manual, Version 3.3, March 2024, X-Spectrum

