API: Python SDK

Chloros Python SDK fornisce accesso programmatico al motore di elaborazione delle immagini Chloros, consentendo l'automazione, flussi di lavoro personalizzati e una perfetta integrazione con le applicazioni Python e le pipeline di ricerca.

Caratteristiche principali

• 🐍 Python nativo - API pulito e Pythonic per l'elaborazione delle immagini

• 🔧 Accesso completo a API - Controllo completo sull'elaborazione Chloros

• 🚀 Automazione - Creazione di flussi di lavoro personalizzati per l'elaborazione in batch

• 🔗 Integrazione - Incorporare Chloros nelle applicazioni Python esistenti

• 📊 Pronto per la ricerca - Perfetto per le pipeline di analisi scientifica

• ⚡ Elaborazione parallela - Scalabile in base ai core della CPU (Chloros+)

Requisiti

Requisito	Dettagli
Chloros Desktop	Deve essere installato localmente
Licenza	Chloros+ (abbonamento a pagamento richiesto)
Sistema operativo	Windows 10/11 (64 bit)
Python	Python 3.7 o superiore
Memoria	Minimo 8 GB di RAM (consigliati 16 GB)
Internet	Necessario per l'attivazione della licenza

Requisiti di licenza: Python SDK richiede un abbonamento a pagamento Chloros+ per l'accesso a API. I piani standard (gratuiti) non consentono l'accesso a API/SDK. Visita https://cloud.mapir.camera/pricing per effettuare l'aggiornamento.

Avvio rapido

Installazione

Installare tramite pip:

pip install chloros-sdk

Configurazione iniziale: prima di utilizzare SDK, attiva la licenza Chloros+ aprendo Chloros, Chloros (Browser) o Chloros CLI e accedendo con le proprie credenziali. Questa operazione deve essere eseguita una sola volta.

Utilizzo di base

Elaborare una cartella con poche righe:

from chloros_sdk import process_folder

# One-line processing
results = process_folder("C:\\DroneImages\\Flight001")

Controllo completo

Per flussi di lavoro avanzati:

from chloros_sdk import ChlorosLocal

# Initialize SDK
chloros = ChlorosLocal()

# Create project
chloros.create_project("MyProject", camera="Survey3N_RGN")

# Import images
chloros.import_images("C:\\DroneImages\\Flight001")

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

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

---

Guida all'installazione

Prerequisiti

Prima di installare SDK, assicurarsi di avere:

1. Chloros Desktop installato (download)

2. Python 3.7+ installato (python.org)

3. Licenza Chloros+ attiva (aggiornamento)

Installazione tramite pip

Installazione standard:

pip install chloros-sdk

Con supporto per il monitoraggio dei progressi:

pip install chloros-sdk[progress]

Installazione di sviluppo:

pip install chloros-sdk[dev]

Verifica dell'installazione

Verifica che SDK sia installato correttamente:

import chloros_sdk
print(f"Chloros SDK version: {chloros_sdk.__version__}")

---

Configurazione iniziale

Attivazione della licenza

SDK utilizza la stessa licenza di Chloros, Chloros (Browser) e Chloros CLI. Attivare una volta tramite la GUI o CLI:

1. Aprire Chloros o Chloros (Browser)ed effettuare il login nella scheda Utente . Oppure, apriCLI.

2. Inserisci le tue credenziali Chloros+ ed effettua il login

3. La licenza viene memorizzata nella cache locale (persiste anche dopo il riavvio)

Configurazione una tantum: dopo aver effettuato l'accesso tramite la GUI o CLI, SDK utilizza automaticamente la licenza memorizzata nella cache. Non è necessaria alcuna autenticazione aggiuntiva!

Logout: gli utenti SDK possono cancellare programmaticamente le credenziali memorizzate nella cache utilizzando il metodo logout(). Vedere metodo logout() nella documentazione di riferimento API.

Test di connessione

Verificare che SDK sia in grado di connettersi a Chloros:

from chloros_sdk import ChlorosLocal

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

# Check status
status = chloros.get_status()
print(f"Backend running: {status['running']}")

---

Riferimento API

Classe ChlorosLocal

Classe principale per l'elaborazione delle immagini locali Chloros.

Costruttore

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

Parametri:

Parametro	Tipo	Impostazione predefinita	Descrizione
api_url	str	"http://localhost:5000"	URL del backend locale Chloros
auto_start_backend	bool	True	Avvia automaticamente il backend se necessario
backend_exe	str	None (rilevamento automatico)	Percorso dell'eseguibile del backend
timeout	int	30	Timeout della richiesta in secondi
backend_startup_timeout	int	60	Timeout per l'avvio del backend (secondi)

Esempi:

# Default (auto-start backend)
chloros = ChlorosLocal()

# Connect to running backend
chloros = ChlorosLocal(auto_start_backend=False)

# Custom backend path
chloros = ChlorosLocal(backend_exe="C:/Custom/chloros-backend.exe")

# Custom timeout
chloros = ChlorosLocal(timeout=60)

---

Metodi

create_project(project_name, camera=None)

Crea un nuovo progetto Chloros.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
project_name	str	Sì	Nome del progetto
camera	str	No	Modello della telecamera (ad es. "Survey3N_RGN", "Survey3W_OCN")

Restituisce: dict - Risposta alla creazione del progettoEsempio:

# Basic project
chloros.create_project("DroneField_A")

# With camera template
chloros.create_project("DroneField_A", camera="Survey3N_RGN")

---

import_images(folder_path, recursive=False)

Importa immagini da una cartella.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
folder_path	str/Path	Sì	Percorso della cartella con le immagini
recursive	bool	No	Cerca sottocartelle (impostazione predefinita: False)

Restituisce: dict - Risultati dell'importazione con conteggio dei fileEsempio:

# Import from folder
chloros.import_images("C:\\DroneImages\\Flight001")

# Import recursively
chloros.import_images("C:\\DroneImages", recursive=True)

---

configure(**settings)

Configura le impostazioni di elaborazione.

Parametri:

Parametro	Tipo	Predefinito	Descrizione
debayer	str	"Alta qualità (più veloce)"	Metodo Debayer
vignette_correction	bool	True	Abilita correzione vignetta
reflectance_calibration	bool	True	Abilita calibrazione riflettanza
indices	list	None	Indici di vegetazione da calcolare
export_format	str	"TIFF (16 bit)"	Formato di output
ppk	bool	False	Abilita correzioni PPK
custom_settings	dict	None	Impostazioni personalizzate avanzate

Formati di esportazione:

• "TIFF (16-bit)" - Consigliato per GIS/fotogrammetria

• "TIFF (32-bit, Percent)" - Analisi scientifica

• "PNG (8-bit)" - Ispezione visiva

• "JPG (8-bit)" - Output compresso

**Indici disponibili:**NDVI, NDRE, GNDVI, OSAVI, CIG, EVI, SAVI, MSAVI, MTVI2 e altri.Esempio:

# Basic configuration
chloros.configure(
    vignette_correction=True,
    reflectance_calibration=True,
    indices=["NDVI", "NDRE"]
)

# Advanced configuration
chloros.configure(
    debayer="High Quality (Faster)",
    vignette_correction=True,
    reflectance_calibration=True,
    ppk=True,
    export_format="TIFF (32-bit, Percent)",
    indices=["NDVI", "NDRE", "GNDVI", "OSAVI", "CIG"]
)

---

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

Elabora le immagini del progetto.

Parametri:

Parametro	Tipo	Predefinito	Descrizione
mode	str	"parallel"	Modalità di elaborazione: "parallel" o "seriale"
wait	bool	True	Attendere il completamento
progress_callback	callable	None	Funzione di callback di avanzamento (progress, msg)
poll_interval	float	2.0	Intervallo di polling per l'avanzamento (secondi)

Restituisce: dict - Risultati dell'elaborazione

Modalità parallela: richiede la licenza Chloros+. Si adatta automaticamente ai core della CPU (fino a 16 worker).

Esempio:

# Simple processing
results = chloros.process()

# With progress monitoring
def show_progress(progress, message):
    print(f"[{progress}%] {message}")

chloros.process(
    mode="parallel",
    progress_callback=show_progress,
    wait=True
)

# Fire-and-forget (non-blocking)
chloros.process(wait=False)

---

get_config()

Ottieni la configurazione corrente del progetto.

Restituisce: dict - Configurazione corrente del progettoEsempio:

config = chloros.get_config()
print(config['Project Settings'])

---

get_status()

Ottiene le informazioni sullo stato del backend.

Restituisce: dict - Stato del backendEsempio:

status = chloros.get_status()
print(f"Running: {status['running']}")
print(f"URL: {status['url']}")

---

shutdown_backend()

Spegne il backend (se avviato da SDK).

Esempio:

chloros.shutdown_backend()

---

logout()

Cancella le credenziali memorizzate nella cache dal sistema locale.

Descrizione:

Esegue il logout in modo programmatico rimuovendo le credenziali di autenticazione memorizzate nella cache. Ciò è utile per:

• Passare da un account Chloros+ a un altro

• Cancellare le credenziali in ambienti automatizzati

• Motivi di sicurezza (ad esempio, rimuovere le credenziali prima della disinstallazione)

Restituisce: dict - Risultato dell'operazione di disconnessioneEsempio:

from chloros_sdk import ChlorosLocal

# Initialize SDK
chloros = ChlorosLocal()

# Clear cached credentials
result = chloros.logout()
print(f"Logout successful: {result}")

# After logout, login required via GUI/CLI/Browser before next SDK use

Riautenticazione richiesta: Dopo aver chiamato logout(), è necessario effettuare nuovamente il login tramite Chloros, Chloros (Browser) o Chloros CLI prima di utilizzare SDK.

---

Funzioni di utilità

process_folder(folder_path, **options)

Funzione di utilità su una riga per elaborare una cartella.

Parametri:

Parametro	Tipo	Predefinito	Descrizione
folder_path	str/Path	Obbligatorio	Percorso della cartella con le immagini
project_name	str	Generato automaticamente	Nome del progetto
camera	str	None	Modello della fotocamera
indices	list	["NDVI"]	Indici da calcolare
vignette_correction	bool	True	Abilita correzione vignettatura
reflectance_calibration	bool	True	Abilita calibrazione riflettanza
export_format	str	"TIFF (16 bit)"	Formato di output
mode	str	"parallel"	Modalità di elaborazione
progress_callback	callable	None	Richiamo di avanzamento

Restituisce: dict - Risultati dell'elaborazioneEsempio:

from chloros_sdk import process_folder

# Simple one-liner
results = process_folder("C:\\DroneImages\\Flight001")

# With custom settings
results = process_folder(
    "C:\\DroneImages\\Flight001",
    project_name="Field_A_Survey",
    camera="Survey3N_RGN",
    indices=["NDVI", "NDRE", "GNDVI"],
    mode="parallel"
)

# With progress monitoring
def show_progress(progress, message):
    print(f"[{progress}%] {message}")

results = process_folder(
    "C:\\DroneImages\\Flight001",
    progress_callback=show_progress
)

---

Supporto Context Manager

SDK supporta i context manager per la pulizia automatica:

from chloros_sdk import ChlorosLocal

# Auto-cleanup when done
with ChlorosLocal() as chloros:
    chloros.create_project("MyProject")
    chloros.import_images("C:\\Images")
    chloros.configure(indices=["NDVI"])
    chloros.process()
# Backend automatically shut down here

---

Esempi completi

Esempio 1: elaborazione di base

Elaborazione di una cartella con impostazioni predefinite:

from chloros_sdk import process_folder

# Process with default settings
results = process_folder("C:\\Datasets\\Field_A_2025_01_15")

print(f"Processing complete: {results}")

---

Esempio 2: flusso di lavoro personalizzato

Controllo completo sulla pipeline di elaborazione:

from chloros_sdk import ChlorosLocal

# Initialize SDK
chloros = ChlorosLocal()

# Create project with camera template
chloros.create_project("Research_Plot_A", camera="Survey3N_RGN")

# Import images
import_results = chloros.import_images("C:\\Research\\PlotA")
print(f"Imported {len(import_results.get('files', []))} images")

# Configure advanced settings
chloros.configure(
    debayer="High Quality (Faster)",
    vignette_correction=True,
    reflectance_calibration=True,
    ppk=False,
    export_format="TIFF (16-bit)",
    indices=["NDVI", "NDRE", "GNDVI", "OSAVI"]
)

# Process with progress monitoring
def show_progress(progress, message):
    print(f"Progress: {progress}% - {message}")

chloros.process(
    mode="parallel",
    progress_callback=show_progress,
    wait=True
)

print("Processing complete!")

---

Esempio 3: elaborazione batch di più cartelle

Elaborazione di più set di dati di volo:

from chloros_sdk import ChlorosLocal
from pathlib import Path

# Initialize SDK once
chloros = ChlorosLocal()

# List of flight folders
flights = [
    "C:\\Datasets\\Flight_001",
    "C:\\Datasets\\Flight_002",
    "C:\\Datasets\\Flight_003"
]

for flight_path in flights:
    flight_name = Path(flight_path).name
    print(f"\n{'='*60}")
    print(f"Processing: {flight_name}")
    print('='*60)
    
    try:
        # Create project
        chloros.create_project(flight_name, camera="Survey3N_RGN")
        
        # Import images
        chloros.import_images(flight_path)
        
        # Configure
        chloros.configure(
            vignette_correction=True,
            reflectance_calibration=True,
            indices=["NDVI", "NDRE", "GNDVI"]
        )
        
        # Process
        chloros.process(mode="parallel", wait=True)
        
        print(f"✓ {flight_name} completed successfully")
    
    except Exception as e:
        print(f"✗ {flight_name} failed: {e}")

print("\n" + "="*60)
print("All flights processed!")

---

Esempio 4: integrazione della pipeline di ricerca

Integrazione di Chloros con l'analisi dei dati:

from chloros_sdk import ChlorosLocal
import pandas as pd
import matplotlib.pyplot as plt

# Initialize Chloros
chloros = ChlorosLocal()

# Field survey data
surveys = [
    {"name": "Plot_A", "folder": "C:\\Research\\PlotA", "biomass": 4500},
    {"name": "Plot_B", "folder": "C:\\Research\\PlotB", "biomass": 3800},
    {"name": "Plot_C", "folder": "C:\\Research\\PlotC", "biomass": 5200}
]

results = []

for survey in surveys:
    # Process with Chloros
    chloros.create_project(survey['name'])
    chloros.import_images(survey['folder'])
    chloros.configure(indices=["NDVI", "NDRE"])
    chloros.process(mode="parallel", wait=True)
    
    # Get results
    config = chloros.get_config()
    
    # Extract NDVI values (example - adjust based on your needs)
    # In real implementation, you would read the processed TIFF files
    
    results.append({
        'plot': survey['name'],
        'biomass': survey['biomass'],
        # Add your NDVI extraction here
    })

# Statistical analysis
df = pd.DataFrame(results)
print("\nResults:")
print(df)

# Create correlation plot
# plt.scatter(df['ndvi'], df['biomass'])
# plt.xlabel('NDVI')
# plt.ylabel('Biomass (kg/ha)')
# plt.title('NDVI vs Biomass Correlation')
# plt.show()

---

Esempio 5: Monitoraggio personalizzato dello stato di avanzamento

Monitoraggio avanzato dello stato di avanzamento con registrazione:

from chloros_sdk import ChlorosLocal
from datetime import datetime
import logging

# Setup logging
logging.basicConfig(
    filename=f'processing_{datetime.now():%Y%m%d_%H%M%S}.log',
    level=logging.INFO,
    format='%(asctime)s - %(message)s'
)

# Progress callback with logging
def log_progress(progress, message):
    log_msg = f"[{progress}%] {message}"
    logging.info(log_msg)
    print(log_msg)

# Process with logging
chloros = ChlorosLocal()
chloros.create_project("LoggedProcess")
chloros.import_images("C:\\DroneImages")
chloros.configure(indices=["NDVI", "NDRE"])

logging.info("Starting processing...")
chloros.process(
    mode="parallel",
    progress_callback=log_progress,
    wait=True
)
logging.info("Processing complete!")

---

Esempio 6: Gestione degli errori

Gestione degli errori robusta per l'uso in produzione:

from chloros_sdk import ChlorosLocal
from chloros_sdk.exceptions import (
    ChlorosError,
    ChlorosBackendError,
    ChlorosLicenseError,
    ChlorosProcessingError
)

def process_safely(folder_path):
    """Process with comprehensive error handling"""
    try:
        with ChlorosLocal() as chloros:
            chloros.create_project("SafeProcess")
            chloros.import_images(folder_path)
            chloros.configure(indices=["NDVI"])
            chloros.process()
            
        return True, "Success"
    
    except ChlorosLicenseError as e:
        return False, f"License error: {e}. Upgrade to Chloros+ at cloud.mapir.camera/pricing"
    
    except ChlorosBackendError as e:
        return False, f"Backend error: {e}. Ensure Chloros Desktop is installed."
    
    except ChlorosProcessingError as e:
        return False, f"Processing error: {e}"
    
    except FileNotFoundError as e:
        return False, f"Folder not found: {e}"
    
    except ChlorosError as e:
        return False, f"Chloros error: {e}"
    
    except Exception as e:
        return False, f"Unexpected error: {e}"

# Use the safe function
success, message = process_safely("C:\\DroneImages\\Flight001")
if success:
    print(f"✓ {message}")
else:
    print(f"✗ {message}")

---

Esempio 7: Gestione account e logout

Gestione delle credenziali a livello di programmazione:

from chloros_sdk import ChlorosLocal

def switch_account():
    """Clear credentials to switch to a different account"""
    try:
        chloros = ChlorosLocal()
        
        # Clear current credentials
        result = chloros.logout()
        print("✓ Credentials cleared successfully")
        print("Please log in with new account via Chloros, Chloros (Browser), or CLI")
        
        return True
    
    except Exception as e:
        print(f"✗ Logout failed: {e}")
        return False

def secure_cleanup():
    """Remove credentials for security purposes"""
    try:
        chloros = ChlorosLocal()
        chloros.logout()
        print("✓ Credentials removed for security")
        
    except Exception as e:
        print(f"Warning: Cleanup error: {e}")

# Switch accounts
if switch_account():
    print("\nRe-authenticate via Chloros GUI/CLI/Browser before next SDK use")

# Or perform secure cleanup
# secure_cleanup()

---

Esempio 8: Strumento da riga di comando

Creazione di uno strumento CLI personalizzato con SDK:

#!/usr/bin/env python
"""
Custom Chloros CLI Tool
Process multiple folders from command line
"""

import sys
import argparse
from pathlib import Path
from chloros_sdk import process_folder

def main():
    parser = argparse.ArgumentParser(description='Custom Chloros Processor')
    parser.add_argument('folders', nargs='+', help='Folders to process')
    parser.add_argument('--indices', nargs='+', default=['NDVI'],
                       help='Indices to calculate (default: NDVI)')
    parser.add_argument('--camera', default=None,
                       help='Camera template')
    parser.add_argument('--format', default='TIFF (16-bit)',
                       help='Export format')
    parser.add_argument('--logout', action='store_true',
                       help='Clear cached credentials before processing')
    
    args = parser.parse_args()
    
    # Handle logout if requested
    if args.logout:
        from chloros_sdk import ChlorosLocal
        chloros = ChlorosLocal()
        chloros.logout()
        print("Credentials cleared. Please re-login via Chloros GUI/CLI/Browser.")
        return 0
    
    successful = []
    failed = []
    
    for folder in args.folders:
        folder_path = Path(folder)
        
        if not folder_path.exists():
            print(f"✗ Skipping {folder}: not found")
            failed.append(folder)
            continue
        
        print(f"\nProcessing: {folder_path.name}...")
        
        try:
            process_folder(
                folder_path,
                camera=args.camera,
                indices=args.indices,
                export_format=args.format
            )
            print(f"✓ {folder_path.name} complete")
            successful.append(folder)
        
        except Exception as e:
            print(f"✗ {folder_path.name} failed: {e}")
            failed.append(folder)
    
    # Summary
    print(f"\n{'='*60}")
    print(f"Summary: {len(successful)} successful, {len(failed)} failed")
    
    return 0 if not failed else 1

if __name__ == '__main__':
    sys.exit(main())

Utilizzo:

# Process multiple folders
python my_processor.py "C:\Flight001" "C:\Flight002" --indices NDVI NDRE GNDVI

# Clear cached credentials
python my_processor.py --logout

---

Gestione delle eccezioni

SDK fornisce classi di eccezioni specifiche per diversi tipi di errore:

Gerarchia delle eccezioni

ChlorosError                    # Base exception
├── ChlorosBackendError        # Backend startup/connection issues
├── ChlorosLicenseError        # License validation issues
├── ChlorosConnectionError     # Network/connection failures
├── ChlorosProcessingError     # Image processing failures
├── ChlorosAuthenticationError # Authentication failures
└── ChlorosConfigurationError  # Configuration errors

Esempi di eccezioni

from chloros_sdk import ChlorosLocal
from chloros_sdk.exceptions import *

try:
    chloros = ChlorosLocal()
    chloros.process()

except ChlorosLicenseError:
    print("Chloros+ license required. Upgrade at cloud.mapir.camera/pricing")

except ChlorosBackendError:
    print("Backend failed to start. Ensure Chloros Desktop is installed.")

except ChlorosProcessingError as e:
    print(f"Processing failed: {e}")

except ChlorosError as e:
    print(f"General Chloros error: {e}")

---

Argomenti avanzati

Configurazione backend personalizzata

Utilizzare una posizione o una configurazione backend personalizzata:

chloros = ChlorosLocal(
    backend_exe="C:\\Custom\\chloros-backend.exe",
    api_url="http://localhost:5001",  # Custom port
    timeout=60,                        # Longer timeout
    backend_startup_timeout=120        # 2 minutes startup
)

Elaborazione non bloccante

Avviare l'elaborazione e continuare con altre attività:

# Start processing (non-blocking)
chloros.process(wait=False)

# Do other work here...
print("Processing started in background...")

# Check status later
import time
while True:
    status = chloros.get_config()
    if status.get('processing_complete'):
        break
    time.sleep(5)

print("Processing complete!")

Gestione della memoria

Per set di dati di grandi dimensioni, elaborare in batch:

from pathlib import Path

base_folder = Path("C:\\LargeDataset")
batch_size = 100

# Get all image files
images = list(base_folder.glob("*.RAW"))

# Process in batches
for i in range(0, len(images), batch_size):
    batch = images[i:i+batch_size]
    batch_folder = base_folder / f"batch_{i//batch_size}"
    
    # Create batch folder and move images
    # ... (implementation details)
    
    # Process batch
    process_folder(batch_folder)

---

Risoluzione dei problemi

Il backend non si avvia

Problema: SDK non riesce ad avviare il backend.Soluzioni:

1. Verificare che Chloros Desktop sia installato:

import os
backend_path = r"C:\Program Files\MAPIR\Chloros\resources\backend\chloros-backend.exe"
print(f"Backend exists: {os.path.exists(backend_path)}")

1. Verificare che Windows Firewall non stia bloccando

2. Provare il percorso manuale del backend:

chloros = ChlorosLocal(backend_exe="C:\\Path\\To\\chloros-backend.exe")

---

Licenza non rilevataProblema: SDK avvisa della mancanza della licenzaSoluzioni:

1. Aprire Chloros, Chloros (browser) o Chloros CLI ed effettuare il login.

2. Verificare che la licenza sia memorizzata nella cache:

from pathlib import Path
import os

# Check cache location (Windows)
cache_path = Path(os.getenv('APPDATA')) / 'Chloros' / 'cache'
print(f"Cache exists: {cache_path.exists()}")

1. In caso di problemi con le credenziali, cancellare le credenziali memorizzate nella cache ed effettuare nuovamente il login:

from chloros_sdk import ChlorosLocal

# Clear cached credentials
chloros = ChlorosLocal()
chloros.logout()

# Then login again via Chloros, Chloros (Browser), or Chloros CLI

1. Contattare l'assistenza: [e-mail]

---

Errori di importazioneProblema: ModuleNotFoundError: No module named 'chloros_sdk'Soluzioni:

# Verify installation
pip show chloros-sdk

# Reinstall if needed
pip uninstall chloros-sdk
pip install chloros-sdk

# Check Python environment
python -c "import sys; print(sys.path)"

---

Timeout di elaborazioneProblema: Timeout di elaborazioneSoluzioni:

1. Aumentare il timeout:

chloros = ChlorosLocal(timeout=120)  # 2 minutes

1. Elaborare batch più piccoli

2. Controllare lo spazio disponibile su disco

3. Monitorare le risorse di sistema

---

Porta già in usoProblema: Porta backend 5000 occupataSoluzioni:

# Use different port
chloros = ChlorosLocal(api_url="http://localhost:5001")

Oppure individuare e chiudere il processo in conflitto:

# PowerShell
Get-NetTCPConnection -LocalPort 5000

---

Suggerimenti sulle prestazioni

Ottimizzare la velocità di elaborazione

1. Utilizzare la modalità parallela (richiede Chloros+)

chloros.process(mode="parallel")  # Up to 16 workers

1. Ridurre la risoluzione di output (se accettabile)

chloros.configure(export_format="PNG (8-bit)")  # Faster than TIFF

1. Disattiva gli indici non necessari

# Only calculate needed indices
chloros.configure(indices=["NDVI"])  # Not all indices

1. Elabora su SSD (non su HDD)***

Ottimizzazione della memoria

Per set di dati di grandi dimensioni:

# Process in batches instead of all at once
# See "Memory Management" in Advanced Topics

---

Elaborazione in background

Liberare Python per altre attività:

chloros.process(wait=False)  # Non-blocking

# Continue with other work
# ...

---

Esempi di integrazione

Integrazione con Django

# views.py
from django.http import JsonResponse
from chloros_sdk import process_folder

def process_images_view(request):
    if request.method == 'POST':
        folder_path = request.POST.get('folder_path')
        
        try:
            results = process_folder(folder_path)
            return JsonResponse({'success': True, 'results': results})
        except Exception as e:
            return JsonResponse({'success': False, 'error': str(e)})

Flask API

# app.py
from flask import Flask, request, jsonify
from chloros_sdk import process_folder

app = Flask(__name__)

@app.route('/api/process', methods=['POST'])
def process():
    data = request.get_json()
    folder_path = data.get('folder_path')
    
    try:
        results = process_folder(folder_path)
        return jsonify({'success': True, 'results': results})
    except Exception as e:
        return jsonify({'success': False, 'error': str(e)}), 500

if __name__ == '__main__':
    app.run()

Jupyter Notebook

# notebook.ipynb
from chloros_sdk import ChlorosLocal
import matplotlib.pyplot as plt

# Initialize
chloros = ChlorosLocal()

# Process
chloros.create_project("JupyterTest")
chloros.import_images("C:\\Data")
chloros.configure(indices=["NDVI"])

# Progress in notebook
from IPython.display import clear_output

def notebook_progress(progress, message):
    clear_output(wait=True)
    print(f"Progress: {progress}%")
    print(message)

chloros.process(progress_callback=notebook_progress)

# Visualize results
# ... (your visualization code)

---

Domande frequenti

D: SDK richiede una connessione Internet?

R: Solo per l'attivazione iniziale della licenza. Dopo aver effettuato l'accesso tramite Chloros, Chloros (browser) o Chloros CLI, la licenza viene memorizzata nella cache locale e funziona offline per 30 giorni.***

D: Posso utilizzare SDK su un server senza GUI?R: Sì! Requisiti:

• Windows Server 2016 o versioni successive

• Chloros installato (una sola volta)

• Licenza attivata su qualsiasi macchina (licenza memorizzata nella cache copiata sul server)

---

D: Qual è la differenza tra Desktop, CLI e SDK?

Funzionalità	GUI Desktop	CLI Riga di comando	Python SDK
Interfaccia	Puntamento e clic	Comando	Python API
Ideale per	Lavoro visivo	Scripting	Integrazione
Automazione	Limitata	Buona	Eccellente
Flessibilità	Base	Buona	Massima
Licenza	Chloros+	Chloros+	Chloros+

D: Posso distribuire app create con SDK?R: Il codice SDK può essere integrato nelle vostre applicazioni, ma:

• Gli utenti finali devono avere installato Chloros

• Gli utenti finali devono disporre di licenze Chloros+ attive

• La distribuzione commerciale richiede una licenza OEM

Contattare [e-mail] per richieste relative alle licenze OEM.

---

D: Come si aggiorna SDK?

pip install --upgrade chloros-sdk

---

D: Dove vengono salvate le immagini elaborate?

Per impostazione predefinita, nel percorso del progetto:

Project_Path/
└── MyProject/
    └── Survey3N_RGN/          # Processed outputs

---

D: Posso elaborare immagini da script Python in esecuzione secondo una pianificazione?R: Sì! Utilizza Windows Task Scheduler con script Python:

# scheduled_processing.py
from chloros_sdk import process_folder

# Process today's flights
results = process_folder("C:\\Flights\\Today")

Pianifica tramite Task Scheduler l'esecuzione giornaliera.

---

D: SDK supporta async/await?R: La versione attuale è sincrona. Per un comportamento asincrono, utilizza wait=False o esegui in un thread separato:

import threading

def process_thread():
    chloros.process()

thread = threading.Thread(target=process_thread)
thread.start()

# Continue with other work...

---

D: Come posso passare da un account Chloros+ all'altro?R: Utilizza il metodo logout() per cancellare le credenziali memorizzate nella cache, quindi effettua nuovamente l'accesso con il nuovo account:

from chloros_sdk import ChlorosLocal

# Clear current credentials
chloros = ChlorosLocal()
chloros.logout()

# Re-login via Chloros, Chloros (Browser), or Chloros CLI with new account

Dopo aver effettuato il logout, autenticarsi con il nuovo account tramite GUI, browser o CLI prima di utilizzare nuovamente SDK.

---

Assistenza

Documentazione

• Riferimento API: questa pagina

Canali di assistenza

• E-mail: [e-mail]

• Sito web: https://www.mapir.camera/community/contact

• Prezzi: https://cloud.mapir.camera/pricing

Codice di esempio

Tutti gli esempi qui elencati sono stati testati e sono pronti per la produzione. Copiateli e adattateli al vostro caso d'uso.

---

LicenzaSoftware proprietario - Copyright (c) 2025 MAPIR Inc.

SDK richiede un abbonamento attivo a Chloros+. È vietato l'uso, la distribuzione o la modifica non autorizzati.