# EZannot: annotate and measure the annotated with ease.
[](https://pypi.org/project/EZannot/)
[](https://pypi.org/project/EZannot/)
[](https://pepy.tech/project/EZannot)
<p> </p>
## Key features & Workflow:
1. AI ([SAM2](https://github.com/facebookresearch/sam2)) help enables manual annotation of an object/region with a ***single*** `Mouse click`.
2. The augmentation is up to ***135 X*** for each image and enhances the generalizability of training.
3. Manually annotate a few to train an AI ***Annotator*** and use it to automatically annotate the rest.
4. Refine the annotations performed by the ***automatic Annotator*** and iterate a better Annotator.
5. All the annotations can be ***quantified by diverse measurements*** such as area and pixel intensity.
6. Totally ***free***, and keeps your data ***private*** since the work is done locally on your computer.
<p> </p>
## How to use?
**1. For manual annotation, turn on the `AI Help` button to annotate the outlines of objects or regions with ease.**
> [!TIP]
> To include more images to an annotated dataset, simply put new images inside the folder of the annotated dataset.
> [!TIP]
> To merge multiple annotated datasets, merge the folders (rename the annotation files to avoid overwriting).
> [!TIP]
> To visualize or refine the annotations, use `Manual Annotation` unit, navigate to the folder that stores the images and the annotation files, select the images you want to visualize or refine, go through all the buttons, and `Start to annotate images`.
<p> </p>
**<ins>Some demo</ins>:**
<p> </p>
> [!NOTE]
> Click `Mouse left` to detect the outline and hit `Enter` to specify the classname to finalize the annotation.
> [!TIP]
> Speed up by hiting `Enter` instead of using mouse to click "OK" so that no need to move mouse back and forth.
> [!TIP]
> If there is no object of interest in an image, simply don't do any annotation and proceed to the next image.
>
> In this way, the 'null' image will be marked as 'null' in the annotation file.
<p> </p>
> [!NOTE]
> Another `Mouse left` click to include an additional area in an annotation before finalizing it.
<p> </p>
> [!NOTE]
> A `Mouse left` click to select a region and a `Mouse right` click to exclude some areas in an annotation.
<p> </p>
> [!NOTE]
> To modify the polygon of an annotation, press `Shift` once to enter or exit the editing mode.
<p> </p>
> [!NOTE]
> To show the classnames of all annotations, press `Space` once to enter or exit the showing mode.
<p> </p>
> [!NOTE]
> To delete an annotation, a `Mouse right` click on any area inside the outline of that annotation.
<p> </p>
**2. Augments each annotated image to 134 additional manipulated images to improve the model training.**
> [!TIP]
> The augmented images and the annotation file for them are stored in the output folder you specified. The annotation file for the original, unaugmented images is stored in the original image folder.
<p> </p>
**3. Provides quantitative measures, such as area and pixel intensity, for each annotated object/region.**
<p> </p>
## Installation
<p> </p>
> [!IMPORTANT]
> If you are a [LabGym](https://github.com/umyelab/LabGym) or [FluoSA](https://github.com/umyelab/FluoSA) user, you need to install EZannot under a different version of Python3 or environment. For example, if your LabGym/FluoSA is installed under Python3.10, you need to install EZannot under another version of Python (e.g., Python3.12). This is because LabGym/FluoSA and EZannot use different versions of PyTorch and different versions of PyTorch cannot be installed within the same Python3 or environment. You can use commands like `py -3.10` and `py -3.11` to activate different versions of Python3.
<p> </p>
EZannot works for Windows, Mac and Linux systems. Installation steps can vary for different systems. But in general, you need to:
1) Install Python3 (>=3.10)
2) If using an NVIDIA GPU, set up CUDA (v11.8) and install PyTorch with cu118 support
3) Install EZannot with pip
4) Download [SAM2](https://github.com/facebookresearch/sam2) models for AI-help in annotation
<p> </p>
### Windows
You need to access the terminal. To do this, open the start menu by clicking the `Win` key, type "PowerShell", and hit enter. All terminal commands going forward should be entered in this terminal.
1. Install Python>=3.10, for example, [Python 3.12](https://www.python.org/downloads/release/python-31210/).
Scroll down to the bottom and click the `Windows installer (64-bit)` option. Run the installer and select "Add python to path" and "Disable long path limit".
2. If you're using an NVIDIA GPU, install CUDA Toolkit 11.8 and cuDNN, and install PyTorch>=v2.5.1 with cu118 support.
First, install [CUDA Toolkit 11.8](https://developer.nvidia.com/cuda-11-8-0-download-archive?target_os=Windows&target_arch=x86_64). Select your version of Windows, select "exe (local)," then click "Download."
Next, install [cuDNN](https://developer.nvidia.com/rdp/cudnn-archive). You will need to register an NVIDIA Developer account, which you can do for free. You can choose cuDNN v8.9.7 that supports CUDA toolkit v11.8. Choose 'Local Installer for Windows (Zip)', download and extract it. And then copy the three folders 'bin', 'lib', and 'include' into where the CUDA toolkit is installed (typically, 'C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\'), and replace all the three folders with the same names.
Finally, install PyTorch>=v2.5.1 with cu118 support:
```pwsh-session
py -3.12 -m pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu118
```
3. Upgrade `pip`, `wheel`, `setuptools`.
```pwsh-session
py -3.12 -m pip install --upgrade pip wheel setuptools
```
4. Install EZannot via `pip`.
```pwsh-session
py -3.12 -m pip install EZannot
```
5. Setup SAM2 models.
Find the 'site-packages' folder where the EZannot is by typing:
```pwsh-session
py -3.12 -m pip show EZannot
```
And download the [SAM2 models](https://github.com/yujiahu415/EZannot/tree/main/SAM2%20models) ('large' is more accurate but slower than 'tiny'; if you have a good GPU, go for large). You can download the individual files and organize them in the same way as they appear in the folder, and put them (e.g., the entire 'large' folder) inside the '.../site-packages/EZannot/sam2 models/' folder for easy access within EZannot's user interface, or store them somewhere else and choose the option of 'Choose a new directory of the SAM2 model' and navigate to where you store them to access these models.
<p> </p>
### Mac
You need to access the terminal. Use `Cmd+Space` to enter Spotlight Search, then search for "Terminal" and hit enter to open it. Next, follow these steps.
1. Install Python>=3.10, for example, [Python 3.12](https://www.python.org/downloads/release/python-31210/).
Scroll down to the bottom and click the `macOS 64-bit universal2 installer` option. Run the installer and select "Add python to path".
2. Upgrade `pip`, `wheel`, `setuptools`.
```console
python3.12 -m pip install --upgrade pip wheel setuptools
```
3. Install EZannot via `pip`.
```console
python3.12 -m pip install EZannot
```
4. Setup SAM2 models.
Find the 'site-packages' folder where the EZannot is by typing:
```console
python3.12 -m pip show EZannot
```
And download the [SAM2 models](https://github.com/yujiahu415/EZannot/tree/main/SAM2%20models) ('large' is more accurate but slower than 'tiny'). You can download the individual files and organize them in the same way as they appear in the folder, and put them (e.g., the entire 'large' folder) inside the '.../site-packages/EZannot/sam2 models/' folder for easy access within EZannot's user interface, or store them somewhere else and choose the option of 'Choose a new directory of the SAM2 model' and navigate to where you store them to access these models.
## Launch the user interface
1. Launch EZannot:
```pwsh-session
EZannot
```
The user interface may take a few minutes to start up during the first launch. If the user interface fails to initiate with the above method, which is typcially because the python3 is not added into the 'PATH' environmental variable, you can still make it show up by three lines of code:
```pwsh-session
py -3.12
```
```pwsh-session
from EZannot import __main__
```
```pwsh-session
__main__.main()
```
2. There's a hint for each button in the user interface:
Raw data
{
"_id": null,
"home_page": null,
"name": "EZannot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "Image annotation, Quantification of annotated objects, AI-assisted annotation, Image augmentation",
"author": null,
"author_email": "Yujia Hu <yujiahu415@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4d/39/ef77c1023b7320248c1fb1ccaba7233441eec5c04928cf9fd7c90ed4b889/ezannot-0.9.8.tar.gz",
"platform": null,
"description": "# EZannot: annotate and measure the annotated with ease.\n\n[](https://pypi.org/project/EZannot/)\n[](https://pypi.org/project/EZannot/)\n[](https://pepy.tech/project/EZannot)\n\n<p> </p>\n\n## Key features & Workflow:\n\n1. AI ([SAM2](https://github.com/facebookresearch/sam2)) help enables manual annotation of an object/region with a ***single*** `Mouse click`.\n\n2. The augmentation is up to ***135 X*** for each image and enhances the generalizability of training.\n\n3. Manually annotate a few to train an AI ***Annotator*** and use it to automatically annotate the rest.\n\n4. Refine the annotations performed by the ***automatic Annotator*** and iterate a better Annotator.\n\n5. All the annotations can be ***quantified by diverse measurements*** such as area and pixel intensity.\n\n6. Totally ***free***, and keeps your data ***private*** since the work is done locally on your computer.\n\n<p> </p>\n\n## How to use?\n\n**1. For manual annotation, turn on the `AI Help` button to annotate the outlines of objects or regions with ease.**\n\n> [!TIP]\n> To include more images to an annotated dataset, simply put new images inside the folder of the annotated dataset.\n\n> [!TIP]\n> To merge multiple annotated datasets, merge the folders (rename the annotation files to avoid overwriting).\n\n> [!TIP]\n> To visualize or refine the annotations, use `Manual Annotation` unit, navigate to the folder that stores the images and the annotation files, select the images you want to visualize or refine, go through all the buttons, and `Start to annotate images`.\n\n<p> </p>\n\n**<ins>Some demo</ins>:**\n\n<p> </p>\n\n \n\n > [!NOTE]\n > Click `Mouse left` to detect the outline and hit `Enter` to specify the classname to finalize the annotation.\n\n > [!TIP]\n > Speed up by hiting `Enter` instead of using mouse to click \"OK\" so that no need to move mouse back and forth.\n\n > [!TIP]\n > If there is no object of interest in an image, simply don't do any annotation and proceed to the next image.\n > \n > In this way, the 'null' image will be marked as 'null' in the annotation file.\n\n<p> </p>\n\n \n\n > [!NOTE]\n > Another `Mouse left` click to include an additional area in an annotation before finalizing it.\n\n<p> </p>\n \n \n\n > [!NOTE]\n > A `Mouse left` click to select a region and a `Mouse right` click to exclude some areas in an annotation.\n\n<p> </p>\n \n \n\n > [!NOTE]\n > To modify the polygon of an annotation, press `Shift` once to enter or exit the editing mode.\n\n<p> </p>\n\n \n\n > [!NOTE]\n > To show the classnames of all annotations, press `Space` once to enter or exit the showing mode.\n\n<p> </p>\n\n \n\n > [!NOTE]\n > To delete an annotation, a `Mouse right` click on any area inside the outline of that annotation.\n\n<p> </p>\n\n**2. Augments each annotated image to 134 additional manipulated images to improve the model training.**\n\n \n\n> [!TIP]\n> The augmented images and the annotation file for them are stored in the output folder you specified. The annotation file for the original, unaugmented images is stored in the original image folder.\n\n<p> </p>\n\n**3. Provides quantitative measures, such as area and pixel intensity, for each annotated object/region.**\n\n \n\n<p> </p>\n\n## Installation\n\n<p> </p>\n\n> [!IMPORTANT]\n> If you are a [LabGym](https://github.com/umyelab/LabGym) or [FluoSA](https://github.com/umyelab/FluoSA) user, you need to install EZannot under a different version of Python3 or environment. For example, if your LabGym/FluoSA is installed under Python3.10, you need to install EZannot under another version of Python (e.g., Python3.12). This is because LabGym/FluoSA and EZannot use different versions of PyTorch and different versions of PyTorch cannot be installed within the same Python3 or environment. You can use commands like `py -3.10` and `py -3.11` to activate different versions of Python3.\n\n<p> </p>\n\nEZannot works for Windows, Mac and Linux systems. Installation steps can vary for different systems. But in general, you need to:\n1) Install Python3 (>=3.10)\n2) If using an NVIDIA GPU, set up CUDA (v11.8) and install PyTorch with cu118 support\n3) Install EZannot with pip\n4) Download [SAM2](https://github.com/facebookresearch/sam2) models for AI-help in annotation\n\n<p> </p>\n\n### Windows\n\nYou need to access the terminal. To do this, open the start menu by clicking the `Win` key, type \"PowerShell\", and hit enter. All terminal commands going forward should be entered in this terminal.\n\n1. Install Python>=3.10, for example, [Python 3.12](https://www.python.org/downloads/release/python-31210/).\n\n Scroll down to the bottom and click the `Windows installer (64-bit)` option. Run the installer and select \"Add python to path\" and \"Disable long path limit\".\n\n2. If you're using an NVIDIA GPU, install CUDA Toolkit 11.8 and cuDNN, and install PyTorch>=v2.5.1 with cu118 support.\n\n First, install [CUDA Toolkit 11.8](https://developer.nvidia.com/cuda-11-8-0-download-archive?target_os=Windows&target_arch=x86_64). Select your version of Windows, select \"exe (local),\" then click \"Download.\"\n\n Next, install [cuDNN](https://developer.nvidia.com/rdp/cudnn-archive). You will need to register an NVIDIA Developer account, which you can do for free. You can choose cuDNN v8.9.7 that supports CUDA toolkit v11.8. Choose 'Local Installer for Windows (Zip)', download and extract it. And then copy the three folders 'bin', 'lib', and 'include' into where the CUDA toolkit is installed (typically, 'C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v11.8\\'), and replace all the three folders with the same names.\n\n Finally, install PyTorch>=v2.5.1 with cu118 support:\n\n ```pwsh-session\n py -3.12 -m pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu118\n ```\n\n3. Upgrade `pip`, `wheel`, `setuptools`.\n \n ```pwsh-session\n py -3.12 -m pip install --upgrade pip wheel setuptools\n ```\n\n4. Install EZannot via `pip`.\n \n ```pwsh-session\n py -3.12 -m pip install EZannot\n ```\n \n5. Setup SAM2 models.\n \n Find the 'site-packages' folder where the EZannot is by typing:\n ```pwsh-session\n py -3.12 -m pip show EZannot\n ```\n And download the [SAM2 models](https://github.com/yujiahu415/EZannot/tree/main/SAM2%20models) ('large' is more accurate but slower than 'tiny'; if you have a good GPU, go for large). You can download the individual files and organize them in the same way as they appear in the folder, and put them (e.g., the entire 'large' folder) inside the '.../site-packages/EZannot/sam2 models/' folder for easy access within EZannot's user interface, or store them somewhere else and choose the option of 'Choose a new directory of the SAM2 model' and navigate to where you store them to access these models.\n\n<p> </p>\n\n### Mac\n\nYou need to access the terminal. Use `Cmd+Space` to enter Spotlight Search, then search for \"Terminal\" and hit enter to open it. Next, follow these steps.\n\n1. Install Python>=3.10, for example, [Python 3.12](https://www.python.org/downloads/release/python-31210/).\n\n Scroll down to the bottom and click the `macOS 64-bit universal2 installer` option. Run the installer and select \"Add python to path\".\n\n2. Upgrade `pip`, `wheel`, `setuptools`.\n\n ```console\n python3.12 -m pip install --upgrade pip wheel setuptools\n ```\n\n3. Install EZannot via `pip`.\n \n ```console\n python3.12 -m pip install EZannot\n ```\n\n4. Setup SAM2 models.\n \n Find the 'site-packages' folder where the EZannot is by typing:\n ```console\n python3.12 -m pip show EZannot\n ```\n And download the [SAM2 models](https://github.com/yujiahu415/EZannot/tree/main/SAM2%20models) ('large' is more accurate but slower than 'tiny'). You can download the individual files and organize them in the same way as they appear in the folder, and put them (e.g., the entire 'large' folder) inside the '.../site-packages/EZannot/sam2 models/' folder for easy access within EZannot's user interface, or store them somewhere else and choose the option of 'Choose a new directory of the SAM2 model' and navigate to where you store them to access these models.\n\n \n\n## Launch the user interface\n\n1. Launch EZannot:\n\n ```pwsh-session\n EZannot\n ```\n \n The user interface may take a few minutes to start up during the first launch. If the user interface fails to initiate with the above method, which is typcially because the python3 is not added into the 'PATH' environmental variable, you can still make it show up by three lines of code:\n ```pwsh-session\n py -3.12\n ```\n ```pwsh-session\n from EZannot import __main__\n ```\n ```pwsh-session\n __main__.main()\n ```\n\n2. There's a hint for each button in the user interface:\n\n \n \n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "Annotate images and measure the annotated with ease.",
"version": "0.9.8",
"project_urls": {
"Homepage": "https://github.com/yujiahu415/EZannot"
},
"split_keywords": [
"image annotation",
" quantification of annotated objects",
" ai-assisted annotation",
" image augmentation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cf625c2c3e148e922c7520c43bd51ddb57765b8703a215994f381dc11a8b9a06",
"md5": "06f28ed46d1497dc5916bbd16122969c",
"sha256": "9c1df830ceadf97faf48b8d75f52c10122b56d7f4788c137e3fafd7e5bf84ef5"
},
"downloads": -1,
"filename": "ezannot-0.9.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "06f28ed46d1497dc5916bbd16122969c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 844079,
"upload_time": "2025-08-17T07:19:43",
"upload_time_iso_8601": "2025-08-17T07:19:43.384703Z",
"url": "https://files.pythonhosted.org/packages/cf/62/5c2c3e148e922c7520c43bd51ddb57765b8703a215994f381dc11a8b9a06/ezannot-0.9.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4d39ef77c1023b7320248c1fb1ccaba7233441eec5c04928cf9fd7c90ed4b889",
"md5": "9ccf1931871ad7f2f5d2eaa9be0dc770",
"sha256": "a14f1d5f78a691bfac38844404ffab7b2169878510f4ea7e84f0e941b3acb17d"
},
"downloads": -1,
"filename": "ezannot-0.9.8.tar.gz",
"has_sig": false,
"md5_digest": "9ccf1931871ad7f2f5d2eaa9be0dc770",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 651425,
"upload_time": "2025-08-17T07:19:45",
"upload_time_iso_8601": "2025-08-17T07:19:45.190172Z",
"url": "https://files.pythonhosted.org/packages/4d/39/ef77c1023b7320248c1fb1ccaba7233441eec5c04928cf9fd7c90ed4b889/ezannot-0.9.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-17 07:19:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yujiahu415",
"github_project": "EZannot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ezannot"
}
JSON
