Metadata-Version: 2.4
Name: magtrack
Version: 0.7.7
Summary: Convert images of beads into XYZ positions
Author-email: James London <7jameslondon@gmail.com>
License-Expression: GPL-3.0
Project-URL: Homepage, https://github.com/7jameslondon/MagTrack
Project-URL: Source, https://github.com/7jameslondon/MagTrack
Project-URL: Documentation, https://magtrack.readthedocs.io
Project-URL: Issues, https://github.com/7jameslondon/MagTrack/issues
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: license
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11.1
Provides-Extra: cpu
Provides-Extra: cu11
Requires-Dist: cupy-cuda11x>=12.0; extra == "cu11"
Provides-Extra: cu12
Requires-Dist: cupy-cuda12x>=13.0; extra == "cu12"
Provides-Extra: cu13
Requires-Dist: cupy-cuda13x>=13.0; extra == "cu13"
Provides-Extra: benchmark
Requires-Dist: matplotlib; extra == "benchmark"
Provides-Extra: test
Requires-Dist: matplotlib; extra == "test"
Requires-Dist: pytest; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: sphinx-autoapi; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: sphinx-book-theme; extra == "docs"
Dynamic: license-file

<h1 align="center">
<img src="https://raw.githubusercontent.com/7jameslondon/MagTrack/refs/heads/master/assets/logo.png" width="300">
</h1><br>

[![PyPi](https://img.shields.io/pypi/v/magtrack)](https://pypi.org/project/magtrack/)
[![Docs](https://img.shields.io/readthedocs/magtrack/latest.svg)](https://magtrack.readthedocs.io)
[![Testing](https://github.com/7jameslondon/MagTrack/actions/workflows/tests.yml/badge.svg)](https://github.com/7jameslondon/MagTrack/actions/workflows/tests.yml)
[![Paper](https://img.shields.io/badge/DOI-10.1101/2025.10.31.685671-blue)](https://doi.org/10.1101/2025.10.31.685671)

[MagTrack](https://github.com/7jameslondon/MagTrack/) is a free open-source Python library for tracking symmetric beads in [single-molecule magnetic tweezers](https://doi.org/10.1007/978-1-0716-3377-9_18) experiments. 

* Sub-pixel XYZ coordinates
* GPU accelerated (optional, requires a CUDA-capable GPU)
* Python notebook included with [examples](https://colab.research.google.com/github/7jameslondon/MagTrack/blob/master/examples/examples.ipynb)
* [Documented](https://magtrack.readthedocs.io/en/stable/), [tested](https://github.com/7jameslondon/MagTrack/actions/workflows/python-package.yml), and [benchmarked](https://magtrack.readthedocs.io/en/stable/benchmarking.html)
* Only depends on [NumPy](https://numpy.org), [SciPy](https://scipy.org), and [CuPy](https://cupy.dev)
* Runs on Windows, macOS, and Linux
* [Easy installation](https://magtrack.readthedocs.io/en/stable/getting_started.html#installation) with pip

Try a demo in a Google Colab notebook [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/7jameslondon/MagTrack/blob/master/examples/examples.ipynb)

<h3 align="center">
<img src="https://raw.githubusercontent.com/7jameslondon/MagTrack/refs/heads/master/assets/demo.gif" width="600">
</h3>

## ⏳ Install
Get started with MagTrack by following the [installation instructions](https://magtrack.readthedocs.io/en/stable/getting_started.html).

## ⚒ Usage
```
import magtrack

# Run the full default XYZ pipeline
x, y, z, profiles = magtrack.stack_to_xyzp(stack)

# Or make your own pipeline from algorithms you prefer
x, y = magtrack.center_of_mass(stack)
x, y = magtrack.auto_conv_sub_pixel(stack, x, y)
profiles = magtrack.fft_profile(stack)
...
```
### More Examples
You can see more examples of how to use MagTrack in [this notebook](https://github.com/7jameslondon/MagTrack/blob/master/examples/examples.ipynb).
Try it out with Google Colab. [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/7jameslondon/MagTrack/blob/master/examples/examples.ipynb)
Or you can [download](https://github.com/7jameslondon/MagTrack/blob/master/examples/examples.ipynb) it and run it on your computer with [Jupyter Notebook](https://jupyter.org/install).

## 📖 Documentation
View the full guide to MagTrack at [magtrack.readthedocs.io](https://magtrack.readthedocs.io)

## 🔬 Live Microscope Control and Acquisition
You can use MagTrack for live video processes using [our sister project MagScope](https://github.com/7jameslondon/MagScope).

## 💬 Support
Report issues and make requests on the [GitHub issue tracker](https://github.com/7jameslondon/MagTrack/issues).<br><br>
Having trouble? Need help? Have suggestions? Want to contribute?<br>
Email us at magtrackandmagscope@gmail.com

