Metadata-Version: 2.4
Name: mcdonald
Version: 0.3.4
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.3.4), tried on Linux and macOS, and on Windows so far only by its automatic tests.

## 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 window opens on its home page. Open a video, choose the segment with the object (and say
how many objects you are looking for, if you know, and anything else you know about the video:
how wide the camera sees, how far away the object is, the size of something in the picture, the
speeds a report gave), and press **Find, follow and measure the object**: the computer finds what moves, takes the most likely thing as the object -- or every
thing worth following, if there are several; or as many of the likeliest as you said -- follows
it, measures how it moved and writes a report, asking nothing on the way; three lights under the
button show the steps as they are done, and while each one runs a coloured oval beside the bar
names the command that does the same from the command line (`look`, `mark`, `layers`...); the bar
says how far it has got in per cent, and a row of jewels under it, one for each part of the step,
lights up as each part is done. With a number given, the run says how many it found
against it, and a thing that is a group of points (a flock) is split into its members, each
followed and reported on its own. The report then appears under the button, the video
still in sight: its conclusion, the numbers found, and "Full report" for the whole of it (a
card for each object, if there were several), which "Save as PDF…" keeps as one file to send;
look at its track sheet and press "I looked" if
the ring is on the object in every frame. Where the report could not give a real speed, the card
asks for what would give one ("Add what you know"), and works the speed out again in a second
or two, without measuring again. Turn on **Advanced** (under the button before it is
pressed, or View → Advanced) to do the three steps one at a time, to choose the object yourself
from the list "Find the object" shows, or to mark it by hand; there, ticking rows on that list
and pressing "Follow and measure the ticked ones" is the same queue, for the things you choose.

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
```

### Sharing an analysis

To hand a video's analysis to someone else -- a colleague, or an agent -- so that they pick up where you left off,
use **File → Share for review…**: write what you would like them to look at (the stretches of frames, and what is
there), add your name and a note, and press **Save a file to send**. That writes one small file, ending in
`.mcdonald`, with your marks, tracks, each object's results and your note. The video itself is not in it: their
copy of mcdonald finds the same video by its catalog name (downloading it if it is not on their computer) and
checks it is the same file.

They open it with **File → Open a shared file…** (or by dropping it on the window, or `mcdonald mark FILE`). The
window opens the same part of the same video, with your marks and every object's track drawn, and a card on the
right with your note, a button for each stretch you named (it plays the stretch and stops at its end), and a box
for their answer -- which saves a file to send back, with your note and theirs. Where the file holds measured
objects, **Measure it again** measures each again as its report says and tells you whether the numbers come back the
same. An agent makes the same file with `mcdonald share make`, reads one with `mcdonald share show`, and measures it
again with `mcdonald share rerun`.

### 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.

### Exercises

To learn **mcdonald** on real videos, try the
[exercises](https://github.com/haqqmisra/mcdonald/tree/main/docs/exercises). Each one gives the
steps in the window and on the command line, and the answer you should get. Start with
[Birdwatching (PR44)](https://github.com/haqqmisra/mcdonald/blob/main/docs/exercises/01-pr44.md).
When you finish one, please
[tell us how it went](https://github.com/haqqmisra/mcdonald/issues/new?template=exercise-result.yml).

## Support

**mcdonald** is free and open source. To support its development, you can
[donate to the mcDonald UAP Toolkit](https://www.zeffy.com/en-US/donation-form/project-janus-mcdonald-uap-toolkit)
through Blue Marble Space, a 501(c)(3) nonprofit. Donations are tax-deductible as allowed by law.

Development of **mcdonald** is supported by a grant from
[Emergent Ventures](https://www.mercatus.org/emergent-ventures) at the Mercatus Center.
The plan to version 1.0 is in [ROADMAP.md](https://github.com/haqqmisra/mcdonald/blob/main/ROADMAP.md).

## License

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