Metadata-Version: 2.4
Name: mcdonald
Version: 0.2.5
Summary: Measurement tools for single-sensor video of unidentified objects: background layers, clip integrity, symbology, angular scale, kinematics, co-motion
Author-email: Jacob Haqq Misra <jacob@bmsis.org>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/haqqmisra/mcdonald
Project-URL: Repository, https://github.com/haqqmisra/mcdonald
Project-URL: Documentation, https://github.com/haqqmisra/mcdonald/blob/main/README-technical.md
Project-URL: Installing, https://github.com/haqqmisra/mcdonald/blob/main/docs/install.md
Keywords: uap,video-forensics,photogrammetry,kinematics,remote-sensing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: X11 Applications :: Qt
Classifier: Environment :: Console
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.7
Requires-Dist: pillow>=9.5
Requires-Dist: PySide6-Essentials>=6.6
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Provides-Extra: gui
Dynamic: license-file

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/haqqmisra/mcdonald/main/docs/logo-dark.png">
  <img alt="mcDonald UAP Toolkit" src="https://raw.githubusercontent.com/haqqmisra/mcdonald/main/docs/logo-light.png" width="420">
</picture>

**mcdonald** is a frame-by-frame analysis toolkit for measuring the kinematics of an unknown
object in a single-camera video.

> "Science is in default for having failed to mount any truly adequate studies of this problem."
>
> — James E. McDonald

**Status:** early test version (0.2.5), tried on Linux and macOS; Windows is next.

## Install

1. Prerequisite: make sure **ffmpeg** is installed:
   `brew install ffmpeg` (Mac), `winget install Gyan.FFmpeg` (Windows),
   `sudo apt install ffmpeg` or `sudo dnf install ffmpeg` (Linux).
2. Install **mcdonald** (needs Python 3.10 or newer):

   ```bash
   python3 -m pip install mcdonald
   ```

3. Check your setup, which also provides instructions on what to do next:

   ```bash
   mcdonald setup
   ```

When a newer version is out, `mcdonald-gui` offers to update itself when it starts, and the
command line prints the command to update with.

New to Python or the terminal? [docs/install.md](https://github.com/haqqmisra/mcdonald/blob/main/docs/install.md) walks through each step in
detail.

## Use

**mcdonald** has a graphical interface and a command-line interface. The software is intended
to be driven by human users and/or AI agents.

The graphical interface is designed to prompt human users through the steps of analysis. To
start the graphical interface:

```bash
mcdonald-gui
```

The command-line interface is designed for developers, advanced users, and AI agents. To start
the command-line interface and see a summary of options:

```bash
mcdonald
```

### Prompting an agent

You can invoke an AI agent to assist at any point in the analysis, whether before or after a
human has looked at the video. Here is a sample prompt that you can pass to your favorite
command-line AI model:

> Please use the mcdonald toolkit to analyze the PR144 video released under PURSUE. Run
> `mcdonald readme` to get started.

## License

Copyright (c) 2026 Jacob Haqq Misra. Released under the [BSD 3-Clause License](https://github.com/haqqmisra/mcdonald/blob/main/LICENSE).
