chloros-sdk 1.1.1

Official Python SDK for MAPIR Chloros image processing

Chloros Python SDK

Official Python SDK for MAPIR Chloros image processing software. Provides programmatic access to the Chloros API for automation, integration, and custom workflows.

🚀 Quick Start

from chloros_sdk import ChlorosLocal
from pathlib import Path

# Initialize SDK (auto-starts backend)
chloros = ChlorosLocal()

# Create project and import images
chloros.create_project("MyProject", camera="Survey3N_RGN")
chloros.import_images(str(Path.home() / "DroneImages" / "Flight001"))

# Configure settings
chloros.configure(
    vignette_correction=True,
    reflectance_calibration=True,
    indices=["NDVI", "NDRE", "GNDVI"]
)

# Process images
chloros.process(mode="parallel", wait=True)

One-Line Processing

from chloros_sdk import process_folder
from pathlib import Path

images_dir = Path.home() / "DroneImages" / "Flight001"
results = process_folder(str(images_dir), indices=["NDVI", "NDRE"])

📋 Requirements

Requirement	Details
Chloros Desktop	Must be installed locally
License	Chloros+ required (paid plan)
Operating System	Windows 10/11 or Linux (64-bit)
Python	Python 3.7 or higher
Memory	8GB RAM minimum (16GB recommended)

⚠️ License Requirement: The Chloros SDK requires an active Chloros+ subscription. Standard (free) plans do not have API access. Upgrade at https://cloud.mapir.camera/pricing

📥 Installation

From PyPI (Recommended)

pip install chloros-sdk

From Source

git clone https://github.com/mapircamera/chloros-sdk.git
cd chloros-sdk
pip install -e .

With Progress Monitoring

pip install chloros-sdk[progress]

Platform-Specific Notes

Linux:

• Requires exiftool: sudo apt install libimage-exiftool-perl
• Data stored in ~/.local/share/chloros (XDG compliant)
• Config stored in ~/.config/chloros

Windows:

• ExifTool bundled with Chloros Desktop
• Data stored in %LOCALAPPDATA%\Chloros

🔬 DAQ Spectral Sensors

The daq.sensors package exposes MAPIR's three spectral sensors (DAQ-U USB, DAQ-M BLE, DAQ-E ethernet) through one unified interface. End users running Chloros get every transport bundled inside chloros-backend / chloros-cli — SDK consumers install transport libs they need (pyserial, bleak, zeroconf) as extras.

from daq.sensors import (
    DAQUSensor, DAQMSensor, DAQESensor,
    discover_all, build_sensor, SensorFleet,
)

# One sensor, one transport — the three classes share a public API.
sensor = DAQESensor(host="daq-e-def330.local", transport="multicast",
                    integration_time=32, frame_avg_num=20)
sensor.connect()

def on_spectrum(spectrum, is_saturated, integration_time, x, y, z):
    print(f"{integration_time} ms  Y={y:.2f}  sat={is_saturated}")

sensor.add_spectrum_callback(on_spectrum)
sensor.start_streaming()
# ... later ...
sensor.stop()

Multi-sensor fleet

# Discover every DAQ sensor visible on the machine / LAN.
devices = discover_all(timeout=5.0)   # DiscoveredSensor per device
sensors = [build_sensor(d, integration_time=32) for d in devices]

fleet = SensorFleet(sensors)
fleet.connect_all()                   # parallel; partial failures OK
fleet.record_all("./out")             # one .daq per sensor
fleet.start_streaming_all()
# ... wait for duration / SIGINT ...
fleet.stop_all()
fleet.close_record_loggers()

Time synchronisation

DAQ-E and LATTICE cameras share a PTP domain anchored by the Chloros host (grandmaster runs inside chloros-backend). When strict frame- to-spectrum alignment matters, pass wait_ptp=True so the sensor blocks until it reaches SLAVE state before streaming:

sensor = DAQESensor(host="daq-e-def330.local", wait_ptp=True)
sensor.connect()          # returns after PTP SLAVE (or 15 s timeout)

See docs/DAQ_SENSOR_GUIDE.md for the full CLI surface, protocol details, and troubleshooting.

📖 Documentation

Complete documentation available at: https://docs.chloros.com/api-python-sdk

🎯 Use Cases

Research & Academia

# Integrate Chloros into analysis pipelines
import chloros_sdk
import pandas as pd

chloros = chloros_sdk.ChlorosLocal()

results = []
for survey in field_surveys:
    chloros.process(survey.images)
    ndvi_data = chloros.get_index_values("NDVI")
    results.append({'chloros_ndvi': ndvi_data, 'biomass': survey.biomass})

df = pd.DataFrame(results)
correlation = df.corr()

Batch Processing

# Process multiple flights automatically
from chloros_sdk import ChlorosLocal

chloros = ChlorosLocal()

for flight in flight_database:
    chloros.create_project(flight.name)
    chloros.import_images(flight.folder)
    chloros.configure(indices=flight.requested_indices)
    chloros.process()

Custom Workflows

# Advanced progress monitoring
from pathlib import Path

def progress_callback(progress, message):
    print(f"[{progress}%] {message}")

chloros = ChlorosLocal()
chloros.create_project("CustomWorkflow")
chloros.import_images(str(Path.home() / "Data"))
chloros.configure(indices=["NDVI", "NDRE"])
chloros.process(progress_callback=progress_callback)

🔑 License Activation

The SDK uses the same license as Chloros Desktop:

1. Open Chloros Desktop GUI
2. Login with your Chloros+ credentials (one-time)
3. SDK automatically uses cached license
4. License persists across reboots (30-day offline support)

🛠️ API Reference

ChlorosLocal Class

Main SDK class for local Chloros processing.

chloros = ChlorosLocal(
    api_url="http://localhost:5000",     # Backend URL
    auto_start_backend=True,             # Auto-start if not running
    backend_exe=None,                    # Auto-detect backend path
    timeout=30                           # Request timeout (seconds)
)

Methods

create_project(project_name, camera=None)

Create a new Chloros project.

import_images(folder_path, recursive=False)

Import images from a folder.

configure(**settings)

Configure processing settings.

process(mode="parallel", wait=True, progress_callback=None)

Start processing images.

get_config()

Get current project configuration.

get_status()

Get backend status.

🔐 Security

• Proprietary Software: Licensed under MAPIR proprietary license
• Local Processing: All processing happens locally (localhost API)
• License Enforcement: Requires active Chloros+ subscription
• No Data Transmission: Images never leave your computer

💡 Examples

See complete examples in the documentation.

🐛 Support

• Email: [e-mail]
• Website: https://www.mapir.camera
• Documentation: https://docs.chloros.com
• Pricing: https://cloud.mapir.camera/pricing

📄 License

Copyright (c) 2026 MAPIR Inc. All rights reserved.

This is proprietary software requiring an active Chloros+ subscription. Unauthorized use, distribution, or modification is prohibited.

🔄 Version History

v1.0.4 (2025)

• Added Linux support
• Cross-platform path handling
• XDG-compliant directories on Linux

v1.0.0 (2025)

• Initial release
• Full API coverage for local processing
• Auto-backend startup
• Progress monitoring support
• Context manager support