<h1 align="center">
    📐 Cursory
</h1>


<p align="center">
    <a href="https://pypi.org/project/cursory/">
        <img alt="Cursory Version" src="https://img.shields.io/pypi/v/cursory&label=Version">
    </a>
    <a href="https://pypi.org/project/cursory/">
        <img alt="Pypi Downloads" src="https://img.shields.io/pepy/dt/cursory?color=seagreen">
    </a>
    <a href="https://github.com/Vinyzu/cursory/blob/main/LICENSE">
        <img src="https://img.shields.io/badge/License-GNU%20GPL-green">
    </a>
    <br/>
    <a href="https://discordapp.com/users/935224495126487150">
        <img src="https://img.shields.io/badge/My_Discord-000?style=for-the-badge&logo=google-chat&logoColor=blue">
    </a>
    <a href="https://ko-fi.com/vinyzu">
        <img src="https://img.shields.io/badge/Buy_Me_A_Coffee-000?style=for-the-badge&logo=ko-fi&logoColor=brown">
    </a>
</p>

#### Cursory - Mouse Trajectory Factory. Generate 100% human-realistic Mouse Trajectories with Timings.

---

## Install it from PyPI

```bash
pip install cursory
```

---

## Basic Usage

```py
from cursory import generate_trajectory

trajectory: list[tuple[float, float]]
timings: list[int]
trajectory, timings = generate_trajectory(target_start=..., target_end=...)
```

---

## Example Trajectories

|                                                       Random Points                                                            |                                                        Same Points                                                           |                                                        Points / Velocity                                                           |
|:------------------------------------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------:|
| <img height="500" alt="Random Points" src="https://github.com/user-attachments/assets/07eaebb0-6798-45d1-9182-2ffd5f1e42d7" /> | <img height="500" alt="Same Points" src="https://github.com/user-attachments/assets/81eb79df-e274-4200-b74c-5f57f4899a3f" /> | <img height="500" alt="SCR-20250920-oegv" src="https://github.com/user-attachments/assets/e7fad0e3-1b56-4c85-a139-42601288701c" /> 

---

## Methodology

Cursory generates Mouse Trajectories following these steps:
1. **Find a close matching human Trajectory**: Cursory has a database of thousands of Trajectories recorded from real humans. It finds the closest matching Trajectory to the target Points with some amount of randomization.
2. **Morph the Trajectory**: The Trajectory is morphed to fit the target Points exactly, while keeping the overall shape as close to the original as possible.
3. **Add Noise**: The Trajectory is jittered and knotted, to alter positions slightly to avoid fingerprinting by hash-fingerprinting.
4. **Regenerating with Timings**: The Trajectory is regenerated using the Trajectory Frequency, with some noise added to the timings to avoid.
5. **Re-Add Noise**: The Trajectory is jittered and knotted, to alter positions slightly to avoid fingerprinting by hash-fingerprinting.
6. **Morph the Trajectory**: The Trajectory is morphed to fit the target Points exactly, while keeping the overall shape to the original as possible.

> [!WARNING]  
> Theoretically, it is possible to detect/fingerprint Mouse Trajectories generated by Cursory. But this would require an amount of compute power which is unfeasible. A greater risk of detection would be bad Trajectories, which is mitigated by the advanced algorithms used by Cursory.


---

## Copyright and License
© [Vinyzu](https://github.com/Vinyzu/)
<br>
[GNU GPL](https://choosealicense.com/licenses/gpl-3.0/)

(Commercial Usage is allowed, but source, license and copyright has to made available. Cursory does not provide and Liability or Warranty)

---

## Thanks to

[Pointergeist](https://github.com/Pointergeist) (For helping me understand Mouse Trajectories better).
<br/>
[sameelarif](https://github.com/sameelarif/) (For his awesome work on [Scribe](https://github.com/sameelarif/scribe))
<br/>
[Margit Antal, Norbert Fejer, Krisztian Buza](https://github.com/margitantal68) (For their work on [SapiMouse](https://ieeexplore.ieee.org/document/9465583))
<br/>
[MIMIC-LOGICS](https://github.com/MIMIC-LOGICS/) (For their [Mouse-Synthesizer](https://github.com/MIMIC-LOGICS/Mouse-Synthesizer))


---

## Disclaimer

This repository is provided for **educational purposes only**. \
No warranties are provided regarding accuracy, completeness, or suitability for any purpose. **Use at your own risk**—the authors and maintainers assume **no liability** for **any damages**, **legal issues**, or **warranty breaches** resulting from use, modification, or distribution of this code.\
**Any misuse or legal violations are the sole responsibility of the user**. 
