Metadata-Version: 2.4
Name: falcocv
Version: 1.1.0
Summary: Modular industrial machine vision environment with a DAG workflow engine and web HMI
Keywords: machine-vision,computer-vision,industrial,workflow,opencv,pyqt
Author: FalcoCV contributors
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Processing
Project-URL: Homepage, https://github.com/jaesc/falcocv
Project-URL: Repository, https://github.com/jaesc/falcocv
Project-URL: Issues, https://github.com/jaesc/falcocv/issues
Requires-Python: <3.14,>=3.13
Requires-Dist: numpy>=1.26
Requires-Dist: setuptools>=83.0.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: opencv-python>=5.0.0
Requires-Dist: PyQt6>=6.5.0
Requires-Dist: PyQt6-QScintilla>=2.14.0
Requires-Dist: pyzbar>=0.1.9
Requires-Dist: pylibdmtx>=0.1.10
Requires-Dist: zxing-cpp<3.1,>=3.0.0
Requires-Dist: python-Levenshtein>=0.26.0
Requires-Dist: python-barcode>=0.16.0
Requires-Dist: fastapi>=0.146.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: websockets>=12.0
Requires-Dist: python-multipart>=0.0.31
Requires-Dist: psutil>=5.9.0
Requires-Dist: PyOpenGL>=3.1.7
Requires-Dist: tifffile>=2023.0.0
Requires-Dist: imagecodecs>=2023.0.0
Requires-Dist: onnxruntime>=1.15.0
Requires-Dist: harvesters>=1.4.3
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0; extra == "dev"
Requires-Dist: pytest-qt>=4.4; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: httpx2>=0.1; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Provides-Extra: plc
Requires-Dist: aphyt>=0.1.18; extra == "plc"
Requires-Dist: pyads>=3.5.0; extra == "plc"
Requires-Dist: python-snap7>=3.3.1; extra == "plc"
Provides-Extra: protocols
Requires-Dist: pymodbus<4,>=3.16; extra == "protocols"
Requires-Dist: asyncua<3,>=2.1; extra == "protocols"
Description-Content-Type: text/markdown

# FalcoCV — Industrial Machine Vision Framework

[![PyPI](https://img.shields.io/pypi/v/falcocv)](https://pypi.org/project/falcocv/)
[![Python](https://img.shields.io/badge/Python-3.13-blue)](https://pypi.org/project/falcocv/)
[![Qt](https://img.shields.io/badge/UI-PyQt6-orange)](https://www.riverbankcomputing.com/software/pyqt/)
[![OpenCV](https://img.shields.io/badge/Vision-OpenCV%205-red)](https://opencv.org/)
[![CI](https://github.com/jaesc/falcocv/actions/workflows/ci.yml/badge.svg)](https://github.com/jaesc/falcocv/actions/workflows/ci.yml)

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="src/falcocv/ui/assets/logo_lockup_dark.png">
  <source media="(prefers-color-scheme: light)" srcset="src/falcocv/ui/assets/logo_lockup_light.png">
  <img src="src/falcocv/ui/assets/logo_lockup_light.png" alt="FalcoCV" width="380">
</picture>

FalcoCV is a modular machine vision environment for industrial automation. It
combines a workflow-driven tool pipeline with real-time image processing,
inspection, depth/3D analysis and camera acquisition, plus a web-based HMI for
operator dashboards.

> FalcoCV is under active development: interfaces and job formats may change
> between releases.

## Highlights

- **Workflow engine** — connect tools in a directed graph; jobs are saved as
  `.cvj` files.
- **Vision toolset** — acquisition, image enhancement, segmentation, template
  and shape matching, code reading, measurement, deep-learning inspection and
  3D analysis.
- **Depth + 3D** - depth/range loading, the native `.fcd` LZ4 container,
  point clouds, plane fitting and a 3D viewer with world-space overlays. See
  [`docs/DEPTH_FORMATS.md`](docs/DEPTH_FORMATS.md) and
  [`docs/3D_CONVENTIONS.md`](docs/3D_CONVENTIONS.md).
- **Fixture system** — per-image coordinate transforms; tools work in
  fixture-relative coordinates.
- **Vector overlays** — annotations are mathematical primitives rendered only
  by visible viewers; source pixels are never modified.
- **Scripting + debugger** — editor, breakpoints, stepping and variable/watch
  panels. HMI runtime objects can be passed to job Python Scripts through the
  shared `context` / `engine_context`; see
  [`docs/HMI_CONTEXT.md`](docs/HMI_CONTEXT.md).
- **HMI designer + web server** — design operator dashboards, deploy them to a
  FastAPI server and open them from any browser.
- **Communications runtime** — generic devices and tags in the `.hmi` project,
  editable from the HMI Designer, with local and live signal monitors, a dummy
  driver with simulated signals, Omron, Beckhoff ADS, Siemens S7 and ADLINK
  DASK I/O drivers, plus Modbus TCP and OPC UA clients and server runtimes.
  Drafts can be saved with missing fields; Deploy and Signal Monitor require a
  complete configuration. See [`docs/COMMS.md`](docs/COMMS.md).
- **Persistent workspace** — window geometry, dock placement, splitter sizes
  and table column widths are restored between runs. Use **View > Reset all
  views** to return the current workspace to its defaults.
- **Camera acquisition** — GigE Vision and USB3 Vision cameras through Harvesters
  and a vendor GenTL producer.

## Screenshots

Generated with the bundled demo project by
[`scripts/capture_readme_screenshots.py`](scripts/capture_readme_screenshots.py).
The 3D view uses a synthetic point cloud; the HMI dashboard image is the
Designer preview with representative runtime values.

<table>
  <tr>
    <td width="50%"><img src="docs/images/vision-editor.png" alt="FalcoCV Vision Editor"></td>
    <td width="50%"><img src="docs/images/vision-3d.png" alt="FalcoCV 3D point-cloud viewer"></td>
  </tr>
  <tr>
    <td><b>Vision Editor</b><br>Workflow, result image and per-tool timing for the
      demo inspection job.</td>
    <td><b>3D analysis</b><br>Interactive point-cloud viewer with a world-space
      ROI and world-coordinate navigation.</td>
  </tr>
  <tr>
    <td><img src="docs/images/hmi-designer.png" alt="FalcoCV HMI Designer"></td>
    <td><img src="docs/images/hmi-dashboard.png" alt="FalcoCV HMI dashboard preview"></td>
  </tr>
  <tr>
    <td><b>HMI Designer</b><br>Job slots, dashboard widgets, live preview and
      deployment controls.</td>
    <td><b>HMI dashboard</b><br>Operator view with verdict, measurement and
      runtime log (preview data).</td>
  </tr>
  <tr>
    <td colspan="2"><img src="docs/images/hmi-servers.png" alt="FalcoCV Modbus and OPC UA server mappings"></td>
  </tr>
  <tr>
    <td colspan="2"><b>Communications servers</b><br>Explicit Modbus TCP and
      OPC UA mappings exposed from HMI communications tags.</td>
  </tr>
</table>

## Install

FalcoCV is distributed as a wheel for Windows x86_64 and Linux x86_64
(CPython 3.13.x):

```bash
python -m pip install falcocv
```

Python 3.13 is the only supported version for this release. The native kernel
ships inside the wheel, so no compiler is needed. On Windows, install the
Microsoft Visual C++ 2015-2022 Redistributable (x64); ONNX Runtime and the
native kernel use that runtime. On platforms without a wheel, `pip` builds it
from the sdist and needs Python 3.13.x, CMake 3.20+ and a C++17 compiler. On
Linux the wheels target glibc 2.34+ (Ubuntu 22.04+, Debian 12+, RHEL 9+), which
is what PyQt6 requires.
GigE and USB3 Vision cameras only need the vendor GenTL producer (`.cti` file);
the Harvesters integration is installed by default.

### From source

Requires CPython 3.13.x:

```bash
git clone https://github.com/jaesc/falcocv.git
cd falcocv
python -m pip install ".[dev]"
```

### PLC communications

The optional PLC extra installs the Omron, Beckhoff and Siemens libraries:

```bash
python -m pip install "falcocv[plc]"
# from source:
python -m pip install -e ".[plc]"
```

It includes `aphyt` (Omron), `pyads` (Beckhoff ADS) and `python-snap7`
(Siemens S7). Driver imports are lazy, so the rest of FalcoCV can be used
without these dependencies. Write verification is opt-in; when enabled,
`write_retries` adds verification retries, while without verification the
driver trusts the library response and never retries. A device configuration
may be saved incomplete (for example Siemens without a host) and completed
later; only Deploy and execution require every field and tag address.
Hardware-specific prerequisites:

- Omron: reachable NJ/NX controller; no persistent dictionary file is used.
- Beckhoff: TwinCAT ADS route configured in the router. The optional
  `ip_address` is only needed for Linux or routed/NAT networks. `TcAdsDll.dll`
  comes from TwinCAT or `%APPDATA%/FalcoCV/native/beckhoff/`.
- Siemens: PUT/GET enabled on S7-1200/1500 and non-optimized DBs for absolute
  addressing. S7-300/400 use absolute addressing normally. The `python-snap7`
  3.x package is pure Python and needs no DLL.
- ADLINK: install the DASK SDK for the card model on Windows x64. FalcoCV
  detects the runtime automatically; if it is not on the system path, use the
  Driver setup actions to select the SDK folder or place the DLLs in
  `%APPDATA%/FalcoCV/native/adlink/`. `Test card` confirms that the card can be
  registered. Digital and analog DASK tags are supported.
- Beckhoff: the Driver setup panel checks `pyads` and `TcAdsDll.dll` and always
  reminds you to configure the ADS route. `Test connection` verifies the route
  and target AMS Net ID before deploying.

For Modbus TCP and OPC UA clients/servers install the protocol extra:

```bash
python -m pip install "falcocv[protocols]"
```

The **Servers** tab exposes existing tags through explicit Modbus TCP or OPC UA
mappings. Modbus has no authentication; OPC UA server security is anonymous in
this first release, so keep both on trusted networks.

### Models

ONNX models are not bundled with the package; they are downloaded on first use
to:

- Windows: `%APPDATA%/FalcoCV/models`
- Linux: `$XDG_DATA_HOME/FalcoCV/models` (or `~/.local/share/FalcoCV/models`)

The splash screen shows progress and startup waits until the models are ready.
To pre-download or repair them:

```bash
falcocv download-models
# or the dedicated entry point
falcocv-download-models
```

To use an existing local bundle instead (offline or pre-provisioned machines),
point `FALCOCV_MODELS_DIR` at the folder that contains the model files.

Downloads come from a GitHub Release. Override the base URL to use a mirror:

```bash
export FALCOCV_MODELS_URL="https://mirror.example.com/falcocv/models-v1"
```

## Run

| Command | What runs |
|---------|-----------|
| `falcocv` or `python -m falcocv` | Vision Editor (desktop) |
| `falcocv-server` | Web server / dashboard |
| `falcocv-hmi` | Standalone HMI Designer |
| `falcocv download-models` | Download/verify ONNX models |

The web dashboard is served at `http://localhost:8000`; HMI pages are available
at `http://localhost:8000/?id=<project_id>`.

## Demo

`examples/demo_inspection.cvj` locates a bracket with **Shape Match**, uses it as
a **fixture**, counts the two through-holes with **Blob Detector** and measures
their distance with **Measurement**:

![Demo result](examples/result_ok.jpg)

```bash
git clone https://github.com/jaesc/falcocv.git
cd falcocv
falcocv run examples/demo_inspection.cvj --output results.json
```

The dataset is 14 synthetic images (10 OK, including cosmetic scratches and
stains; 4 NG: missing/blocked/extra hole and wrong hole spacing). Image
generation, the trained job and the annotated results are scripted and
reproducible — see [`examples/README.md`](examples/README.md). All of it is
original CC0 artwork.

## Architecture

```
src/falcocv/
├── core/        Workflow engine, VisionImage, overlays, ROI, model resolver
├── tools/       Vision tools
├── ui/          PyQt6 widgets, viewers, ROI editors, HMI designer
├── web/         FastAPI server, HMI workers, dashboard
├── main.py      Vision Editor
├── cli.py       `falcocv` / `python -m falcocv`
└── version.py

cpp/kernel/      Native kernel (no OpenCV)
tests/           Pytest suite
```

FalcoCV is Python-first: tools and algorithms use OpenCV/NumPy unless a measured
benchmark justifies native code. The small C++ kernel in `cpp/kernel`
accelerates the hot paths where that win exists (for example point-cloud
generation, plane fitting and template matching). It has no OpenCV dependency;
OpenCV is provided by `opencv-python`.

See [`ARCHITECTURE.md`](ARCHITECTURE.md) for the module layout and
[`benchmarks/`](benchmarks/) for the performance harness.

## Development

```bash
git clone https://github.com/jaesc/falcocv.git
cd falcocv
python -m pip install -e ".[dev]"
pytest -q --ignore=tests/test_trainer_equivalence.py
```

An editable install builds the native kernel through `scikit-build-core`. To run
directly from the source tree, build the kernel once and point `PYTHONPATH` at
`src`:

```bash
build_kernel.bat          # Windows
./build_kernel.sh         # Linux/macOS

set PYTHONPATH=src        # Windows
export PYTHONPATH=src     # Linux/macOS
python -m falcocv
```

### Native kernel

```bat
build_kernel.bat            :: configure + build + deploy to cpp/bin
build_kernel.bat --rebuild  :: clean cache first
build_kernel.bat --clean    :: remove artifacts
```

```bash
./build_kernel.sh
```

Requirements: CMake 3.20+, a C++17 compiler, pybind11 and OpenMP. On Windows,
Visual Studio 2022 with the "Desktop development with C++" workload is enough.
No OpenCV build is required.

## Testing

```bash
pytest -q --ignore=tests/test_trainer_equivalence.py
```

Targeted runs:

```bash
pytest -q -m integration   # headless workflows, jobs, barcode, depth
pytest -q -m ui            # offscreen Qt config dialogs / main window
pytest -q -m web           # FastAPI / HMI endpoints
falcocv self-test          # installation smoke test (also works from a wheel)
```

The suite covers the workflow engine, vision tools, UI (offscreen Qt) and
web/HMI endpoints. The trainer-equivalence test needs the optional training
toolchain (torch/timm) and is excluded.

## License

FalcoCV is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.

FalcoCV is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See [`LICENSE`](LICENSE) for the full text.
