Metadata-Version: 2.4
Name: easylidar
Version: 3.0.0b1
Summary: Control EasyLidar with AI (LiDAR GIS for macOS) from Python: every tool of the app, Batches and scripts.
Author: JuanRa Angulo
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://easylidar-ai.com
Project-URL: Documentation, https://easylidar-ai.com/support/programming/
Keywords: lidar,gis,point cloud,dem,terrain,mcp,easylidar
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# easylidar — control EasyLidar from Python

`easylidar` lets a Python program drive [EasyLidar with AI](https://easylidar-ai.com), the LiDAR GIS for macOS:
every tool of the app (the same ones the assistant and MCP clients use) is a method, and Batches, scripts,
engine jobs and downloads can be followed to the end. It has no dependencies beyond the standard library.

**Requires EasyLidar 3.0 or later** on the same Mac (macOS 13+). Earlier versions cannot start without a window
or open a project by path.

```python
import easylidar

with easylidar.connect() as el:                 # starts EasyLidar without a window if it is not open
    el.open_project("~/Documents/MyProject")    # a project opened at least once from EasyLidar
    run = el.run_batch("Flight 2025", inputs={"resolution": 0.5})
    run.wait(on_line=print)                     # Batch console, line by line
    if run.ok:
        print(el.list_vector_layers())
```

## How it connects

- `connect()` looks for the app (`EASYLIDAR_APP`, `/Applications/EasyLidar with AI.app` or Spotlight). If it is not
  open, it starts it with `--hidden --stay`: no window, an icon in the menu bar, the MCP server on.
- Calls go through the app's own bridge (`EasyLidar with AI --mcp-stdio`), the one Claude Desktop and Codex use:
  the access token stays in the macOS Keychain and never passes through Python.
- `connect(token=…)` talks HTTP to `127.0.0.1:8765` directly, with the token from EasyLidar ▸ Settings ▸
  External AI agents.
- Operations that delete or overwrite data raise `DestructiveNotAllowed` until the user allows them in the same
  settings tab.

## Tools as methods

```python
el.tools                      # name → description and parameters
help(el.run_hillshade)        # description and parameters, as the assistant sees them
el.run_hillshade(file_names=["tile.laz"], products=["SVF"])
el.call("get_app_state")      # the same, by name
```

## Long work

| Helper | Follows | Result |
|---|---|---|
| `el.run_batch(name, inputs, sample, project)` | a Batch from the library | `BatchRun`: `.wait()`, `.ok`, `.lines`, `.status`, `.cancel()` |
| `el.run_script(name=…, source=…, inputs)` | a library script or JavaScript code | `ScriptRun`: `.wait()`, `.ok`, `.value`, `.error` |
| `el.wait_job(job_id, kind="batch" \| "download")` | `run_batch_recipe` / `download_elevation_data` jobs | the job's last state |

`wait(timeout=…)` cancels the run when the time is up.

## Command line

```
python -m easylidar tools
python -m easylidar call list_vector_layers '{}'
python -m easylidar run-batch "Flight 2025" --project ~/Documents/MyProject --input resolution=0.5
python -m easylidar run-script "count tiles" --project ~/Documents/MyProject
```

Exit codes: 0 finished · 1 failed · 2 invalid project, Batch or inputs · 3 time limit · 4 cancelled.

## Limits

- macOS only, with EasyLidar installed. A project folder EasyLidar has never opened cannot be opened from Python:
  macOS keeps the permission only for those (open it once from the app).
- This is "Python drives EasyLidar", not Python inside EasyLidar: scripts that run inside the app are JavaScript.

## Tests

```
cd python && python3 -m unittest discover -s tests -v                       # no app needed
EASYLIDAR_LIVE=1 python3 -m unittest tests.test_client.LiveTests -v        # against the installed app
```

Copyright JuanRa Angulo. Use only under a granted licence.
