Metadata-Version: 2.4
Name: microbridge-lmd
Version: 2.0.0
Summary: NDP/CSV to LMD Converter
Author: Rose Scott
License-Expression: GPL-3.0-or-later
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click
Requires-Dist: customtkinter
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: basedpyright; extra == "dev"
Dynamic: license-file

```zsh
 ___  ____               ______      _     _
 |  \/  (_)              | ___ \    (_)   | |
 | .  . |_  ___ _ __ ___ | |_/ /_ __ _  __| | __ _  ___
 | |\/| | |/ __| '__/ _ \| ___ \ '__| |/ _` |/ _` |/ _ \
 | |  | | | (__| | | (_) | |_/ / |  | | (_| | (_| |  __/
 \_|  |_/_|\___|_|  \___/\____/|_|  |_|\__,_|\__, |\___|
                                              __/ |
                                              |___/
```

---

MicroBridge is a tool that allows file conversion between Slide annotation software like NDP.view2 to an XML format that Leica Microdissection (LMD) microscopes support.

---

# Purpose
Scientists annotate regions of interest in software like NDP.view2, They would then have to re-draw those same annotations in the software for the LMDs.  
MicroBridge takes the annotation files from NDP.view2 and converts them into a format that the LMD can understand, This gives the scientists more time to do experiments rather than annotating files for the 2nd time.

---

# Installation

[![Packaging status](https://repology.org/badge/vertical-allrepos/microbridge-lmd.svg)](https://repology.org/project/microbridge-lmd/versions)

To install select your Operating system and follow one of the sets of instructions:
<details><summary><b>Linux</b></summary>
  
There is a universal way of installing MicroBridge on Linux

<details><summary>pipx</summary>
  
Make sure you have python installed, 
If you do not install python3.12 or above using your systems package manager.  

Then install pipx.
Then run:
```zsh
pipx install microbridge-lmd
```
  
If that does not work you can always overide it and run:
```zsh
pip install microbridge --break-system-packages
```
This will install it with normal pip but can cause issues with your system python.

</details><details><summary>AUR</summary>
  
You can find the package on the AUR 

Use an aur helper like paru by running:
```zsh
paru -S microbridge-lmd
```
Or Yay:
```zsh
yay -S microbridge-lmd
```

Or manually by cloning the package then running:
```zsh
paru -Ui
```
There are more ways of doing this but these are the main ways I know

</details>

I will hopefully get it onto more systems soon like debian (apt), fedora (dnf) and more (hopefully)

---

</details><details><summary><b>MacOS</b></summary>
  
There are 2 Main ways to Install MicroBridge on macOS

<details><summary>Homebrew(Brew)</summary>
  
Install [HomeBrew](https://docs.brew.sh/Installation) if not installed.

Run this in terminal:
```zsh
brew tap Snowman-scott/microbridge https://github.com/Snowman-scott/MicroBridge
brew trust Snowman-scott/microbridge
brew install microbridge-lmd
```

After Install Run:
```zsh
microbridge --install-launcher
```

This will make an entry in your applications menu (the spotlight search)

</details><details><summary>Binary Download</summary>
  
You can go to the [Releases page](https://github.com/Snowman-scott/MicroBridge/releases) and download the MB_MacOS_zip. (M Series processors Only!)  

**Note**: This won't allow you to type `microbridge` anywhere on your machine and run it CLI, The binary is only recommended if you plan on only using the GUI (User interface)  I recommend using the brew install above, pypi, or installing from source if you plan on using the CLI.

I do strongly recommend using Brew as it does a WAY better job than I did and the binary is not fully tested, the brew tap is.

</details>

---

</details><details><summary><b>Windows</b></summary>
  
As of Current there is only one main way of installing MicroBridge on Windows

<details><summary>Binary Download</summary>
  
You can go to the [Releases page](https://github.com/Snowman-scott/MicroBridge/releases) and download the MB_Windows_zip. (x86_64)  

**Note**: This won't allow you to type `microbridge` anywhere on your machine and run it CLI, The binary is only recommended if you plan on only using the GUI (User interface)  I recommend using pypi, or installing from source if you plan on using the CLI.

</details><details><summary>Choco or Scoop</summary>
  
I may add these packages onto choco or scoop later on

</details>

---

</details><details><summary><b>pip & pipx<b></summary>
  
Using pip is not recommended on Linux unless you want to use a virtual environment,  I recommend linux and MacOS users to look in the Linux and macOS areas of this README for more appropriate installation.

<details><summary>pip</summary>
  
To install with pip make sure you have python installed  
Then run:
```zsh
pip install microbridge --break-system-packages
```

**Note:** I do not recommend Doing this on MacOS or Linux as it can break your system python

</details><details><summary>pipx</summary>
  
To install with pipx make sure you have python installed, 
If you do not have python installed then install python3.12 or above.
Then install pipx.

Then run:
```zsh
pipx install microbridge-lmd
```

</details>

---

</details><details><summary><b>Install from source</b></summary>

Make sure python 3.12 or above is installed.

You will also want git.

First Clone the Repo:
```zsh
git clone https://github.com/Snowman-scott/MicroBridge.git
```

Then move into the cloned dir:
```zsh
cd MicroBridge
```

Then Setup a venv:
```zsh
python3 -m .venv venv
```

Activate the vnev:
```zsh
source .venv/bin/activate
```

Then just install microbridge:
```zsh
pip install -e .
```

**Note:** This sets up MicroBridge in a virtual environment(venv), this means the code will only be able to be ran when you have that specific venv active.  I recommend Installing via pip or pipx if you plan to use this day to day, From source is preferred for development

</details></details>

---

# Usage
There are 2 ways to use MicroBridge  
Option 1: Usage via the GUI (graphical user interface)  
Install it first  
And either run
```zsh
microbridge
```
In your terminal and it will open up
Or use the desktop icon / entry to open the program

Option 2: Usage via the terminal
For typical usage you would run
```zsh
microbridge filename.ndpa file2.ndpa file3.ndpa ...
```
There are 2 flags that you can use to help with input and output
Flag 1: Batch processing 
To process a whole folder / directory run
```zsh
microbridge -b directory-path
```
Flag 2: output dir
To set a specific directory / folder for the files be placed into run
```zsh
microbridge filename.ndpa -o 'path/to/dir'
```

You can use both flags with each other
```zsh
microbridge -b 'path/to/.ndpa/dir' -o 'path/to/output/dir'
```

You can also run 
```zsh
microbridge --help
```
This shows you all the commands and a quick run down of what they do

---

# Tests
There is information about running the tests locally in the tests directory of the REPO

You can run this
```zsh
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
pytest
```
to set up the venv and run the tests (or use `python run_tests.py` for the summary table output)

---

## ndpa -> LMD(xml) example
A raw ndpa looks like this:
```xml
<!-- Calibration Point 3 - Circle annotation -->
<ndpviewstate id="3">
  <title>Calibration_3</title>
  <annotation type="circle">
    <x>200000000</x>
    <y>300000000</y>
    <radius>5000000</radius>
  </annotation>
</ndpviewstate>

<!-- RULER - should be SKIPPED -->
<ndpviewstate id="4">
  <title>Measurement_1</title>
  <annotation type="linearmeasure" displayname="AnnotateRuler" color="#ff0000">
    <x1>100000000</x1>
    <y1>100000000</y1>
    <x2>200000000</x2>
    <y2>200000000</y2>
  </annotation>
</ndpviewstate>
```
MicroBridge (currently) converts this to an XML for the LMD's which look like this:
```xml
  <X_CalibrationPoint_3>200000</X_CalibrationPoint_3>
  <Y_CalibrationPoint_3>300000</Y_CalibrationPoint_3>
  <ShapeCount>2</ShapeCount>
  <Shape_1>
    <PointCount>3</PointCount>
    <X_1>300000</X_1>
    <Y_1>400000</Y_1>
    <X_2>350000</X_2>
    <Y_2>400000</Y_2>
    <X_3>350000</X_3>
    <Y_3>450000</Y_3>
  </Shape_1>
```
This example above is cut down for length reasons

If you want to see a real world example and the full example above you can look here:  
[ndpa --> LMD(xml) examples](ndpa_to_LMD_examples/)

---

## Codebase Layout
```
src/
    ├── MicroBridge/
    │   ├── __init__.py
    │   ├── core/
    │   │   ├── __init__.py
    │   │   ├── conversion.py
    │   │   └── utils.py
    │   ├── cli/
    │   │   ├── __init__.py
    │   │   └── main.py
    │   └── gui/
    │       ├── __init__.py
    │       └── main.py
tests/
    ├── __init__.py
    ├── README.md
    ├── test_core.py
    ├── test_gui.py
    ├── test_intergration.py
    ├── test_utils.py
    ├── test_cli.py
    └── test_Data/
        └── All the test data, I am not writing that out...
        
pyproject.toml
run_tests.py

```

---

# Issues
If you have an issue please make an issue here on github  
[Open an issue](https://github.com/Snowman-scott/MicroBridge/issues)  
or [Email me](mailto:rose@killallchickens.org)

---

# License
This project is licensed under the [GNU GPLv3.0 License](LICENSE)   
This is important as it support copyleft! and Free software!  
(Which means a LOT to me)

---

# About the project

<details><summary><b>About the project</b></summary>

The project started off as a simple little file to file converter to seep up scientists workflows, 
Microbridge is now being taken from a grungy little bedroom and being standerdised, made production ready and being improved upon 'with a little help from my friends' over at the sanger Institute.
With their help I am being taken from a Junior software dev and being taught how senior devs work, I thank them profusely for taking me on and helping me learn all these new awesome skills.

MicroBridge will soon (hopefully) be able to convert between Qupath, NDP.View2, and Xenium. 
This is a big step from what the tool once was, and I look forward to seeing how it turns out 

Signed Rs - lead dev

</details>
