![Header](./docs/pyzwoasi-header.png)

# PyZWOASI &middot; <img src="https://github.com/fmargall/pyzwoasi/actions/workflows/deployment.yml/badge.svg" alt="Build status"> <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"> <a href="https://github.com/qoomon/starlines"> <img src="https://starlines.qoo.monster/assets/fmargall/pyzwoasi" align="right" alt="Starline counter"/> </a>

## Overview

PyZWOASI is a lightweight, cross-platform Python binding for the ZWO ASI SDK, allowing you to control and stream data from all ZWO ASI USB cameras directly from Python.

The project provides:

- A low-level ctypes wrapper exposing all original SDK functions
- Full support for exposure, ROI, binning, video capture, etc.
- Cross-platform DLL/SO/Dylib loading (Windows / Linux / macOS)
- Example scripts for live view

It is designed to be simple to use for beginners, while remaining powerful enough for advanced users who require direct access to the underlying SDK.

## Features

- [x] Easy-to-use Python interface class for ZWO ASI cameras `ZWOCamera`
- [x] Live-view with real-time frame display using `OpenCV` 
- [ ] Direct access to all ZWO ASI SDK functions (40 / 43)
   - [ ] Add function `ASIGetVideoDataGPS`
   - [ ] Add function `ASIGetDataAfterExpGPS`
   - [ ] Add function `ASIGPSGetData`
- [x] Cross-platform support (Windows, Linux, MacOS)

## Installation

> [!WARNING]
> If you are working on Windows, the ZWO USB driver must be installed on the system before the module can detect any camera. You can download the latest driver from the [ZWO website > Software > Dekstop App > Windows > Camera Driver](https://www.zwoastro.com/software/). If you are on Linux or MacOS, no additional driver installation is needed.

### (Recommended) Using pip

The safest and easiest way to install up-to-date PyZWOASI is to use its repository from PyPI using `pip` :
```bash
pip install pyzwoasi
```

The installer will take in charge the machine configuration and choose the right compiled library files from ZWO. This means that you will not have useless `.dll` files on your machine, only the needed ones.

> [!NOTE]
> Only installation from `pip` is currently supported. Installation from `conda` or other package managers is not available at the moment but will come. If you do not want to use `pip`, please follow the instructions below to install from source.

### (Alternative) From source

If you want to be part of the development or simply if you want to install the module directly from the sources, you can also clone the repository and run pip from there:
```bash
git clone https://github.com/fmargall/pyzwoasi.git
cd pyzwoasi
pip install -e .
```

## Quick start

### First shot

```python
import pyzwoasi

numOfConnectedCameras = pyzwoasi.getNumOfConnectedCameras()
if (numOfConnectedCameras == 0):
    print("No camera connected")
    exit()

for cameraIndex in range(numOfConnectedCameras):
    with ZWOCamera(cameraIndex) as camera:
        imageData = camera.shot(exposureTime_us = 1000) 
```

### Live view

```python
import pyzwoasi

numOfConnectedCameras = pyzwoasi.getNumOfConnectedCameras()
if (numOfConnectedCameras == 0):
    print("No camera connected")
    exit()

for cameraIndex in range(numOfConnectedCameras):
    with ZWOCamera(cameraIndex) as camera:
        camera.liveView()
```

## Advanced usage

### High-level access (ZWOCamera class)

The `ZWOCamera` class provides a high-level interface to interact with ZWO ASI cameras. It encapsulates common operations such as connecting to the camera, capturing images, and starting live view sessions.

### Low-level access (Direct SDK function calls)

For advanced applications or scientific control, you can call the original ASI SDK functions directly. This is identical to the official C API, just wrapped for Python.

## Contributing

Contributions are welcome! Whether you fix a bug, improve documentation, add support for new SDK functions, or propose new high-level APIs, feel free to open an issue or submit a pull request. 
Please follow the existing coding style and keep the project cross-platform.

### Contributors

<a href="https://github.com/fmargall/pyzwoasi/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=fmargall/pyzwoasi" />
</a>


### Contact

François Margall - fr.margall@proton.me

## License

PyZWOASI is distributed under the MIT License. See `LICENSE.txt` for more information.