# Panoptic 👀
[](https://pypi.org/project/panoptic)
[](https://pypi.org/project/panoptic)
This documentation also exist in [French](https://github.com/CERES-Sorbonne/Panoptic/blob/main/README-FR.md)
## Table of Contents
1. [Description](#description)
2. [Installation](#installation)
1. [Via pip](#via-pip)
2. [Automatic Installation and Launch Scripts (recommended)](#automatic-installation-and-launch-scripts-recommended)
1. [Windows](#windows)
2. [Linux](#linux)
3. [MacOS](#macos)
3. [Docker Installation](#docker-installation)
4. [Installation (development)](#installation-development)
3. [Usage](#usage)
4. [License](#license)
## 1. Description
Panoptic is a tool for exploring and annotating large image corpora, utilizing image analysis and machine learning tools to facilitate these tasks.
Since it requires deep learning libraries, it is recommended to use it on a computer with minimal computing capabilities.
> Warning: Panoptic is still in active development and currently only a prototype. You may encounter bugs, so we recommend using this tool only for testing and not relying on it for significant academic work.
## 2. Installation
### 2.1 Via pip
<p style="color: red;">
Regardless of your OS, you will need Python 3.10 or higher; we recommend using version 3.12.
</p>
<p style="color: red;">
If you are on MacOS, you may need to install the x-tools command line tools. Open a terminal and run the following command:
`xcode-select --install`
Once installed, you can continue with the Panoptic installation.
</p>
Generally, you just need to open a terminal and run the following commands to install and then launch Panoptic:
- `pip3 install panoptic`
- `panoptic`
### 2.2 Automatic Installation and Launch Scripts (recommended)
<p style="color: red;">
The script may ask for your password to install dependencies. This is necessary if you are missing system dependencies to install Panoptic (python, pip, and/or venv).
</p>
#### 2.2.1 Windows
Here are the two commands to run to install Panoptic on Windows:
```powershell
curl -O https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_windows.ps1
powershell -ExecutionPolicy Bypass -File start_panoptic_windows.ps1
```
For more detailed steps:
1. Download the automatic installation and launch script for Panoptic by clicking the following link: [start_panoptic_windows.ps1](https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_windows.ps1) or directly from the terminal with the following command:
```powershell
curl -O https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_windows.ps1
```
2. Run the script by double-clicking the file or using the following command:
```powershell
powershell -ExecutionPolicy Bypass -File start_panoptic_windows.ps1
```
#### Post-installation
After installation, you can launch Panoptic by going back to the folder where you executed the installation script and running the following command:
```powershell
powershell -ExecutionPolicy Bypass -File start-panoptic.ps1
```
#### 2.2.2 Linux
Here are the three commands to run to install Panoptic on Linux:
```bash
wget https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_linux.sh -O start_panoptic_linux.sh
chmod +x start_panoptic_linux.sh
./start_panoptic_linux.sh
```
For more detailed steps:
1. Download the automatic installation and launch script for Panoptic by clicking the following link: [start_panoptic_linux.sh](https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_linux.sh)
or directly from the terminal with the following command:
```bash
wget https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_linux.sh -O start_panoptic_linux.sh
```
2. Make the script executable by using the file properties or with the following command:
```bash
chmod +x start_panoptic_linux.sh
```
3. Run the script (double-click the file or use the following command):
```bash
./start_panoptic_linux.sh
```
You can also specify Panoptic launch parameters using the following command:
```bash
./start_panoptic_linux.sh [-y|--yes|--assume-yes] [-r|--reinstall] [-s|--start-only] [-u|--uninstall] [--no-bin-copy] [--no-update-script] [-h|--help]
```
Available options are:
- `-y`, `--yes` or `--assume-yes`: Use this option to automatically accept all confirmation requests.
- `-r` or `--reinstall`: Use this option to reinstall Panoptic.
- `-s` or `--start-only`: Use this option to launch Panoptic without reinstalling.
- `-u` or `--uninstall`: Use this option to uninstall Panoptic (does not delete data or system dependencies).
- `--no-bin-copy`: Use this option to not copy the Panoptic launch script to the `/usr/local/bin` directory.
- `--no-update-script`: Use this option to not update the Panoptic launch script in the `/usr/local/bin` directory.
- `-h` or `--help`: Use this option to display help.
##### Post-installation
After installation, you can launch Panoptic using the following command:
```bash
start-panoptic
```
You can also specify Panoptic launch parameters using the following command:
```bash
start-panoptic [-y|--yes|--assume-yes] [-r|--reinstall] [-s|--start-only] [-u|--uninstall] [--no-bin-copy] [-no-update-script] [-h|--help]
```
Available options are:
- `-y`, `--yes` or `--assume-yes`: Use this option to automatically accept all confirmation requests.
- `-r` or `--reinstall`: Use this option to reinstall Panoptic.
- `-s` or `--start-only`: Use this option to launch Panoptic without reinstalling.
- `-u` or `--uninstall`: Use this option to uninstall Panoptic (does not delete data or system dependencies).
- `--no-bin-copy`: Use this option to not copy the Panoptic launch script to the `/usr/local/bin` directory.
- `--no-update-script`: Use this option to not update the Panoptic launch script in the `/usr/local/bin` directory.
- `-h` or `--help`: Use this option to display help.
#### 2.2.3 MacOS
Here are the three commands to run to install Panoptic on MacOS:
```bash
curl -O https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_mac.sh
chmod +x start_panoptic_mac.sh
./start_panoptic_mac.sh
```
For more detailed steps:
1. Download the automatic installation and launch script for Panoptic by clicking the following link: [start_panoptic_mac.sh](https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_mac.sh)
2. Make the script executable by using the file properties or with the following command:
```bash
chmod +x start_panoptic_mac.sh
```
3. Run the script (double-click the file or use the following command):
```bash
./start_panoptic_mac.sh
```
#### Post-installation
After installation, you can launch Panoptic by going back to the folder where you executed the installation script and running the following command:
```bash
./start-panoptic.sh
```
### 2.3 Docker Installation
If you encountered issues with the standard installation, or prefer using Docker, an image is available. First, you need to:
#### 2.3.1 Install Docker
- [On MacOS](https://docs.docker.com/desktop/install/mac-install/)
- [On Windows](https://docs.docker.com/desktop/install/windows-install/)
- [On Linux](https://docs.docker.com/desktop/install/linux-install/)
#### Differences from the Python version
In the Docker version, there is no small interface for adding folders or managing projects; you need to directly specify the folders to Docker to work with:
#### 2.3.2 Option 1: One folder for images and Panoptic data:
This requires creating a special folder named "images" within the folder you provide to Panoptic as input. In the following example, you would need a folder named `images` inside `/path/to/your/folder`, resulting in `/path/to/your/folder/images`.
Then run the following command (with Docker already running):
```console
docker run -it -p 8000:8000 -v /path/to/your/folder:/data --name panoptic ceressorbonne/panoptic
```
#### 2.3.3 Option 2: Separate folders for images and Panoptic data:
```console
docker run -it -p 8000:8000 \
-v /path/to/images:/images \
-v /path/to/panoptic/data:/data \
--name panoptic ceressorbonne/panoptic
```
Once launched, visit [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser to access Panoptic.
#### 2.3.4 Post-installation (Docker)
To relaunch Panoptic with Docker after the initial installation:
```console
docker start -ai panoptic
```
You can also specify Panoptic launch parameters as follows:
```console
docker run -it -p 8000:8000 -v /path/to/your/folder:/data --name panoptic ceressorbonne/panoptic [-y|--yes|--assume-yes] [-r|--reinstall] [-s|--start-only] [-u|--uninstall] [--no-bin-copy] [--no-update-script] [-h|--help]
```
Available options are the same as for the Linux installation.
### 2.4 Development Installation
If you want to contribute to Panoptic's development or test the latest unpublished features, you can clone the GitHub repository and install Panoptic in development mode.
#### 2.4.1 Backend Development Only
To test and modify the backend, we provide a pre-built frontend in the backend's `html` folder.
* Navigate to the `panoptic-back` folder.
* To install dependencies:
- `python3 setup.py install` to simply use Panoptic.
- `pip3 install -e .` for development.
- `pip3 install -r requirements.txt` and add `panoptic-back` to `PYTHON_PATH` for development as well.
* Run the backend with `python panoptic/main.py`.
#### 2.4.2 Frontend and Backend Development
1. First, complete the backend installation steps.
2. Navigate to the `panoptic-front` folder.
3. Run `npm install`.
4. Start the frontend server with `npm run dev`.
5. Before starting the backend, set the environment variable `PANOPTIC_ENV` to `DEV` to use the development frontend.
## License
This project is licensed under the MPL-2.0 License - see the [LICENSE](https://github.com/CERES-Sorbonne/Panoptic/blob/main/LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "panoptic",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "Data visualization, Image analysis, Image clustering, Image corpora, Machine learning, Web application",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/18/ff/a0d574a1ee1862cb67186cf5fdb94f495160d2d3d8066c955c3fea3deb51/panoptic-0.4.5.tar.gz",
"platform": null,
"description": "# Panoptic \ud83d\udc40\n\n[](https://pypi.org/project/panoptic)\n[](https://pypi.org/project/panoptic)\n\nThis documentation also exist in [French](https://github.com/CERES-Sorbonne/Panoptic/blob/main/README-FR.md)\n\n\n\n## Table of Contents\n\n1. [Description](#description)\n2. [Installation](#installation)\n 1. [Via pip](#via-pip)\n 2. [Automatic Installation and Launch Scripts (recommended)](#automatic-installation-and-launch-scripts-recommended)\n 1. [Windows](#windows)\n 2. [Linux](#linux)\n 3. [MacOS](#macos)\n 3. [Docker Installation](#docker-installation)\n 4. [Installation (development)](#installation-development)\n3. [Usage](#usage)\n4. [License](#license)\n\n## 1. Description\n\nPanoptic is a tool for exploring and annotating large image corpora, utilizing image analysis and machine learning tools to facilitate these tasks.\n\nSince it requires deep learning libraries, it is recommended to use it on a computer with minimal computing capabilities.\n\n> Warning: Panoptic is still in active development and currently only a prototype. You may encounter bugs, so we recommend using this tool only for testing and not relying on it for significant academic work.\n\n## 2. Installation\n### 2.1 Via pip\n<p style=\"color: red;\">\nRegardless of your OS, you will need Python 3.10 or higher; we recommend using version 3.12.\n</p>\n\n<p style=\"color: red;\">\nIf you are on MacOS, you may need to install the x-tools command line tools. Open a terminal and run the following command:\n`xcode-select --install`\nOnce installed, you can continue with the Panoptic installation.\n</p>\n\nGenerally, you just need to open a terminal and run the following commands to install and then launch Panoptic:\n\n- `pip3 install panoptic`\n- `panoptic`\n\n### 2.2 Automatic Installation and Launch Scripts (recommended)\n<p style=\"color: red;\">\nThe script may ask for your password to install dependencies. This is necessary if you are missing system dependencies to install Panoptic (python, pip, and/or venv).\n</p>\n\n#### 2.2.1 Windows\n\nHere are the two commands to run to install Panoptic on Windows:\n\n```powershell\ncurl -O https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_windows.ps1\npowershell -ExecutionPolicy Bypass -File start_panoptic_windows.ps1\n```\n\n\nFor more detailed steps:\n\n1. Download the automatic installation and launch script for Panoptic by clicking the following link: [start_panoptic_windows.ps1](https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_windows.ps1) or directly from the terminal with the following command:\n\n```powershell\ncurl -O https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_windows.ps1\n```\n\n\n2. Run the script by double-clicking the file or using the following command:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File start_panoptic_windows.ps1\n```\n\n\n#### Post-installation\n\nAfter installation, you can launch Panoptic by going back to the folder where you executed the installation script and running the following command:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File start-panoptic.ps1\n```\n\n\n#### 2.2.2 Linux\nHere are the three commands to run to install Panoptic on Linux:\n```bash\nwget https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_linux.sh -O start_panoptic_linux.sh\nchmod +x start_panoptic_linux.sh\n./start_panoptic_linux.sh\n```\n\nFor more detailed steps:\n1. Download the automatic installation and launch script for Panoptic by clicking the following link: [start_panoptic_linux.sh](https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_linux.sh)\nor directly from the terminal with the following command:\n```bash\nwget https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_linux.sh -O start_panoptic_linux.sh\n```\n2. Make the script executable by using the file properties or with the following command:\n```bash\nchmod +x start_panoptic_linux.sh\n```\n3. Run the script (double-click the file or use the following command):\n```bash\n./start_panoptic_linux.sh\n```\n\nYou can also specify Panoptic launch parameters using the following command:\n```bash\n./start_panoptic_linux.sh [-y|--yes|--assume-yes] [-r|--reinstall] [-s|--start-only] [-u|--uninstall] [--no-bin-copy] [--no-update-script] [-h|--help]\n```\nAvailable options are:\n- `-y`, `--yes` or `--assume-yes`: Use this option to automatically accept all confirmation requests.\n- `-r` or `--reinstall`: Use this option to reinstall Panoptic.\n- `-s` or `--start-only`: Use this option to launch Panoptic without reinstalling.\n- `-u` or `--uninstall`: Use this option to uninstall Panoptic (does not delete data or system dependencies).\n- `--no-bin-copy`: Use this option to not copy the Panoptic launch script to the `/usr/local/bin` directory.\n- `--no-update-script`: Use this option to not update the Panoptic launch script in the `/usr/local/bin` directory.\n- `-h` or `--help`: Use this option to display help.\n\n##### Post-installation\nAfter installation, you can launch Panoptic using the following command:\n```bash\nstart-panoptic\n```\n \nYou can also specify Panoptic launch parameters using the following command:\n```bash\nstart-panoptic [-y|--yes|--assume-yes] [-r|--reinstall] [-s|--start-only] [-u|--uninstall] [--no-bin-copy] [-no-update-script] [-h|--help]\n```\nAvailable options are:\n- `-y`, `--yes` or `--assume-yes`: Use this option to automatically accept all confirmation requests.\n- `-r` or `--reinstall`: Use this option to reinstall Panoptic.\n- `-s` or `--start-only`: Use this option to launch Panoptic without reinstalling.\n- `-u` or `--uninstall`: Use this option to uninstall Panoptic (does not delete data or system dependencies).\n- `--no-bin-copy`: Use this option to not copy the Panoptic launch script to the `/usr/local/bin` directory.\n- `--no-update-script`: Use this option to not update the Panoptic launch script in the `/usr/local/bin` directory.\n- `-h` or `--help`: Use this option to display help.\n\n\n#### 2.2.3 MacOS\nHere are the three commands to run to install Panoptic on MacOS:\n```bash\ncurl -O https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_mac.sh\nchmod +x start_panoptic_mac.sh\n./start_panoptic_mac.sh\n```\n\nFor more detailed steps:\n1. Download the automatic installation and launch script for Panoptic by clicking the following link: [start_panoptic_mac.sh](https://raw.githubusercontent.com/CERES-Sorbonne/Panoptic/refs/heads/main/install/start_panoptic_mac.sh)\n2. Make the script executable by using the file properties or with the following command:\n```bash\nchmod +x start_panoptic_mac.sh\n```\n3. Run the script (double-click the file or use the following command):\n```bash\n./start_panoptic_mac.sh\n```\n\n#### Post-installation\nAfter installation, you can launch Panoptic by going back to the folder where you executed the installation script and running the following command:\n```bash\n./start-panoptic.sh\n```\n\n\n### 2.3 Docker Installation\n\nIf you encountered issues with the standard installation, or prefer using Docker, an image is available. First, you need to:\n\n#### 2.3.1 Install Docker\n- [On MacOS](https://docs.docker.com/desktop/install/mac-install/)\n- [On Windows](https://docs.docker.com/desktop/install/windows-install/)\n- [On Linux](https://docs.docker.com/desktop/install/linux-install/)\n\n#### Differences from the Python version\n\nIn the Docker version, there is no small interface for adding folders or managing projects; you need to directly specify the folders to Docker to work with:\n\n#### 2.3.2 Option 1: One folder for images and Panoptic data:\n\nThis requires creating a special folder named \"images\" within the folder you provide to Panoptic as input. In the following example, you would need a folder named `images` inside `/path/to/your/folder`, resulting in `/path/to/your/folder/images`.\n\nThen run the following command (with Docker already running):\n\n```console\ndocker run -it -p 8000:8000 -v /path/to/your/folder:/data --name panoptic ceressorbonne/panoptic\n```\n\n#### 2.3.3 Option 2: Separate folders for images and Panoptic data:\n\n```console\ndocker run -it -p 8000:8000 \\\n-v /path/to/images:/images \\\n-v /path/to/panoptic/data:/data \\\n--name panoptic ceressorbonne/panoptic\n```\n\nOnce launched, visit [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser to access Panoptic.\n\n#### 2.3.4 Post-installation (Docker)\n\nTo relaunch Panoptic with Docker after the initial installation:\n\n```console\ndocker start -ai panoptic\n```\n\nYou can also specify Panoptic launch parameters as follows:\n\n```console\ndocker run -it -p 8000:8000 -v /path/to/your/folder:/data --name panoptic ceressorbonne/panoptic [-y|--yes|--assume-yes] [-r|--reinstall] [-s|--start-only] [-u|--uninstall] [--no-bin-copy] [--no-update-script] [-h|--help]\n```\n\nAvailable options are the same as for the Linux installation.\n\n### 2.4 Development Installation\n\nIf you want to contribute to Panoptic's development or test the latest unpublished features, you can clone the GitHub repository and install Panoptic in development mode.\n\n#### 2.4.1 Backend Development Only\n\nTo test and modify the backend, we provide a pre-built frontend in the backend's `html` folder.\n* Navigate to the `panoptic-back` folder.\n* To install dependencies:\n - `python3 setup.py install` to simply use Panoptic.\n - `pip3 install -e .` for development.\n - `pip3 install -r requirements.txt` and add `panoptic-back` to `PYTHON_PATH` for development as well.\n* Run the backend with `python panoptic/main.py`.\n\n#### 2.4.2 Frontend and Backend Development\n\n1. First, complete the backend installation steps.\n2. Navigate to the `panoptic-front` folder.\n3. Run `npm install`.\n4. Start the frontend server with `npm run dev`.\n5. Before starting the backend, set the environment variable `PANOPTIC_ENV` to `DEV` to use the development frontend.\n\n\n\n## License\nThis project is licensed under the MPL-2.0 License - see the [LICENSE](https://github.com/CERES-Sorbonne/Panoptic/blob/main/LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Explore and analyze large datasets of images",
"version": "0.4.5",
"project_urls": {
"Documentation": "https://github.com/CERES-Sorbonne/panoptic#readme",
"Issues": "https://github.com/CERES-Sorbonne/panoptic/issues",
"Lab's website": "https://ceres.sorbonne-universite.fr/",
"Repository": "https://github.com/CERES-Sorbonne/panoptic"
},
"split_keywords": [
"data visualization",
" image analysis",
" image clustering",
" image corpora",
" machine learning",
" web application"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7c22e7ee202c92c132319693c7381a49742cc451fab5cc5e7e764c55dc8d3326",
"md5": "e0c28159be9387023302aacf9e222b9c",
"sha256": "dc48dc01032800da8e2a2fa26805f95b44c2fac363f3e74c80be1ec8098107ac"
},
"downloads": -1,
"filename": "panoptic-0.4.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e0c28159be9387023302aacf9e222b9c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 1220545,
"upload_time": "2024-12-18T21:00:02",
"upload_time_iso_8601": "2024-12-18T21:00:02.399201Z",
"url": "https://files.pythonhosted.org/packages/7c/22/e7ee202c92c132319693c7381a49742cc451fab5cc5e7e764c55dc8d3326/panoptic-0.4.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "18ffa0d574a1ee1862cb67186cf5fdb94f495160d2d3d8066c955c3fea3deb51",
"md5": "122bf8b903b55b51e885c4d1e6d64242",
"sha256": "48b1699a94b56f84719828ecfd2172a575399567e45283f70d345a175fb4ba01"
},
"downloads": -1,
"filename": "panoptic-0.4.5.tar.gz",
"has_sig": false,
"md5_digest": "122bf8b903b55b51e885c4d1e6d64242",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 1203571,
"upload_time": "2024-12-18T21:00:05",
"upload_time_iso_8601": "2024-12-18T21:00:05.164112Z",
"url": "https://files.pythonhosted.org/packages/18/ff/a0d574a1ee1862cb67186cf5fdb94f495160d2d3d8066c955c3fea3deb51/panoptic-0.4.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 21:00:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CERES-Sorbonne",
"github_project": "panoptic#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "panoptic"
}
JSON
