# VisioNomicon
VisioNomicon is a powerful Python-based command-line utility tool designed to rename image files using the capabilities of GPT-4o. Descriptive filenames are generated based on a user given template and the content of the image.
![demo][DEMO]
## Features
- Rename image files based on generated filenames from GPT-4V
- Flexible name generation based on user given structure
- Ability to create a mapping file for renamed images
- Execute renaming based on a generated mapping file
- Undo renaming to revert to original filenames
- Verification step for generated names using GPT-4o
- Support for multiple retry attempts in case of validation or errors
- Supported file types: `.png`, `.jpeg`, `.jpg`, `.webp`, `.gif` (non-animated)
## Prerequisites
- Python 3.6+
- Access to OpenAI API with GPT-4o capabilities (API key required)
## Installation
You can install the package using pip via the following command:
```bash
pip install VisioNomicon
```
Alternatively, you can manually install the package by downloading the source distribution and running the following commands:
1. Download the latest source distribution from the [Releases](https://github.com/rehanzo/VisioNomicon/releases) page.
2. Extract the file and navigate to the extracted directory.
3. Run the following command to install:
```bash
pip install .
```
## Usage
To use VisioNomicon, you need to set the `OPENAI_API_KEY` environment variable to your OpenAI API key. This can generally be done with a command like the following:
```bash
export OPENAI_API_KEY='your_api_key_here'
```
Run the script with the desired flags and arguments:
```bash
VisioNomicon [OPTIONS]
```
Or in one single command:
```bash
OPENAI_API_KEY='your_api_key_here' VisioNomicon [OPTIONS]
```
### Options
- `-f`, `--files`: Specify file paths of the images to create mapping for
- `-o`, `--output`: Specify a JSON mapping file to be created with original and new file paths. Defaults to `$XDG_DATA_HOME/visionomicon/mapping-%Y-%m-%d-%H-%M-%S.json`
- `-x`, `--execute`: Execute renaming based on existing mapping file. Calling this without a value uses the most recently created mapping in `$XDG_DATA_HOME/visionomicon`
- `-ox`, `--mapex`: Map and execute renaming in one step
- `-u`, `--undo`: Revert renaming to original filenames using a mapping file. Calling this without a value uses the most recently created mapping in `$XDG_DATA_HOME/visionomicon`
- It is important to note, if the file names or locations change after executing a mapping, you will not be able to undo
- `-t`, `--template`: Define the template for renaming image files, without file extension. It is recommended to use square brackets to define elements of the filename. Defaults to `[SubjectDescription]\_[MainColor/ColorScheme]\_[StyleOrFeel]\_[CompositionElement]`
- `-e`, `--validation-retries`: Specify the number of retries for name validation (defaults to 3)
- `-v`, `--error-retries`: Specify the number of retries in case of OpenAI errors (defaults to 3)
- `-E`, `--ignore-validation-fail`: If validation retries limit is reached, map file to original name instead of returning an error
- `-V`, `--ignore-error-fail`: If error retries limit is reached, map file to original name instead of returning an error
- `-b`, `--create-batch`: Create batch job through OpenAI API.
- `-B`, `--retrieve-batch`: Retrieve batch job output through OpenAI API. Run this 24 hours after creating the batch job.
### Example Commands
```bash
VisioNomicon -f image1.jpg image2.png -ox
```
This is the most straightforward usage. A mapping file is created for the images, placed at the default location (`$XDG_DATA_HOME/visionomicon/mapping-%Y-%m-%d-%H-%M-%S.json`). Immediately afterwards, this file is executed, renaming the files.
```bash
VisioNomicon -f image1.jpg image2.png -o mapping.json -t "[Object]_[Color]_[Style]"
```
This command will create a rename mapping file for `image1.jpg` and `image2.png` based on the provided template and output the mapping to `mapping.json`.
Subsequently, you can execute the mapping, renaming the files.
```bash
VisioNomicon -x mapping.json
```
This can also be done in one single command if you'd like, using `-ox`:
```bash
VisioNomicon -f image1.jpg image2.png -ox mapping.json -t "[Object]_[Color]_[Style]"
```
## Limitations
- GPT-4o is limited in the file types it can handle(.png, .jpeg, .jpg, .webp, non-animated .gif), and the size (up to 20MB)
- With some templates it can be quite finicky, not really generating the filenames you might expect
## Contributing
Contributions are welcome. Please open an issue first to discuss what you would like to change or add.
## License
This project is open-sourced under the [GLP-3.0 License](LICENSE).
## Disclaimer
This tool is not affiliated with OpenAI. The functionality is subject to change based on updates to the API or the terms of service provided by OpenAI.
[DEMO]: https://raw.githubusercontent.com/rehanzo/VisioNomicon/master/assets/demonstration.gif
Raw data
{
"_id": null,
"home_page": "https://github.com/rehanzo/visionomicon",
"name": "VisioNomicon",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "gpt-4 gpt-4v gpt-4o openai renaming images",
"author": "Rehan Rana",
"author_email": "visionomicon@rehanzo.com",
"download_url": "https://files.pythonhosted.org/packages/62/b3/2b907eb74dcf41aa10a93f266c9c3cc28653b660846580d960a416ff5ac9/visionomicon-0.1.7.tar.gz",
"platform": null,
"description": "# VisioNomicon\n\nVisioNomicon is a powerful Python-based command-line utility tool designed to rename image files using the capabilities of GPT-4o. Descriptive filenames are generated based on a user given template and the content of the image.\n\n![demo][DEMO]\n\n## Features\n\n- Rename image files based on generated filenames from GPT-4V\n- Flexible name generation based on user given structure\n- Ability to create a mapping file for renamed images\n- Execute renaming based on a generated mapping file\n- Undo renaming to revert to original filenames\n- Verification step for generated names using GPT-4o\n- Support for multiple retry attempts in case of validation or errors\n- Supported file types: `.png`, `.jpeg`, `.jpg`, `.webp`, `.gif` (non-animated)\n\n## Prerequisites\n\n- Python 3.6+\n- Access to OpenAI API with GPT-4o capabilities (API key required)\n\n## Installation\n\nYou can install the package using pip via the following command:\n\n```bash\npip install VisioNomicon\n```\n\nAlternatively, you can manually install the package by downloading the source distribution and running the following commands:\n\n1. Download the latest source distribution from the [Releases](https://github.com/rehanzo/VisioNomicon/releases) page.\n2. Extract the file and navigate to the extracted directory.\n3. Run the following command to install:\n\n```bash\npip install .\n```\n\n## Usage\n\nTo use VisioNomicon, you need to set the `OPENAI_API_KEY` environment variable to your OpenAI API key. This can generally be done with a command like the following:\n```bash\nexport OPENAI_API_KEY='your_api_key_here'\n```\n\nRun the script with the desired flags and arguments:\n\n```bash\nVisioNomicon [OPTIONS]\n```\n\nOr in one single command:\n\n```bash\nOPENAI_API_KEY='your_api_key_here' VisioNomicon [OPTIONS] \n```\n\n### Options\n\n- `-f`, `--files`: Specify file paths of the images to create mapping for\n- `-o`, `--output`: Specify a JSON mapping file to be created with original and new file paths. Defaults to `$XDG_DATA_HOME/visionomicon/mapping-%Y-%m-%d-%H-%M-%S.json`\n- `-x`, `--execute`: Execute renaming based on existing mapping file. Calling this without a value uses the most recently created mapping in `$XDG_DATA_HOME/visionomicon`\n- `-ox`, `--mapex`: Map and execute renaming in one step\n- `-u`, `--undo`: Revert renaming to original filenames using a mapping file. Calling this without a value uses the most recently created mapping in `$XDG_DATA_HOME/visionomicon`\n - It is important to note, if the file names or locations change after executing a mapping, you will not be able to undo\n- `-t`, `--template`: Define the template for renaming image files, without file extension. It is recommended to use square brackets to define elements of the filename. Defaults to `[SubjectDescription]\\_[MainColor/ColorScheme]\\_[StyleOrFeel]\\_[CompositionElement]`\n- `-e`, `--validation-retries`: Specify the number of retries for name validation (defaults to 3)\n- `-v`, `--error-retries`: Specify the number of retries in case of OpenAI errors (defaults to 3)\n- `-E`, `--ignore-validation-fail`: If validation retries limit is reached, map file to original name instead of returning an error\n- `-V`, `--ignore-error-fail`: If error retries limit is reached, map file to original name instead of returning an error\n- `-b`, `--create-batch`: Create batch job through OpenAI API.\n- `-B`, `--retrieve-batch`: Retrieve batch job output through OpenAI API. Run this 24 hours after creating the batch job.\n\n### Example Commands\n\n```bash\nVisioNomicon -f image1.jpg image2.png -ox\n```\n\nThis is the most straightforward usage. A mapping file is created for the images, placed at the default location (`$XDG_DATA_HOME/visionomicon/mapping-%Y-%m-%d-%H-%M-%S.json`). Immediately afterwards, this file is executed, renaming the files.\n\n```bash\nVisioNomicon -f image1.jpg image2.png -o mapping.json -t \"[Object]_[Color]_[Style]\"\n```\n\nThis command will create a rename mapping file for `image1.jpg` and `image2.png` based on the provided template and output the mapping to `mapping.json`.\n\nSubsequently, you can execute the mapping, renaming the files.\n\n```bash\nVisioNomicon -x mapping.json\n```\n\nThis can also be done in one single command if you'd like, using `-ox`:\n\n```bash\nVisioNomicon -f image1.jpg image2.png -ox mapping.json -t \"[Object]_[Color]_[Style]\"\n```\n\n## Limitations\n\n- GPT-4o is limited in the file types it can handle(.png, .jpeg, .jpg, .webp, non-animated .gif), and the size (up to 20MB)\n- With some templates it can be quite finicky, not really generating the filenames you might expect\n\n## Contributing\n\nContributions are welcome. Please open an issue first to discuss what you would like to change or add.\n\n## License\n\nThis project is open-sourced under the [GLP-3.0 License](LICENSE).\n\n## Disclaimer\n\nThis tool is not affiliated with OpenAI. The functionality is subject to change based on updates to the API or the terms of service provided by OpenAI.\n\n[DEMO]: https://raw.githubusercontent.com/rehanzo/VisioNomicon/master/assets/demonstration.gif \n",
"bugtrack_url": null,
"license": null,
"summary": "A utility leveraging GPT-4o for image file renaming based on content.",
"version": "0.1.7",
"project_urls": {
"Homepage": "https://github.com/rehanzo/visionomicon"
},
"split_keywords": [
"gpt-4",
"gpt-4v",
"gpt-4o",
"openai",
"renaming",
"images"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1c15c3f2ec480d912e0d750cbb599a12bf27ed76a612380f95ecb754743a3435",
"md5": "39b90655a06393e149c1bdc72c9269ce",
"sha256": "2646f9b022c2572344b2d1aed3b296d36682b85eb7e427257514edd1f372b180"
},
"downloads": -1,
"filename": "VisioNomicon-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "39b90655a06393e149c1bdc72c9269ce",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 23148,
"upload_time": "2024-10-05T20:28:51",
"upload_time_iso_8601": "2024-10-05T20:28:51.089678Z",
"url": "https://files.pythonhosted.org/packages/1c/15/c3f2ec480d912e0d750cbb599a12bf27ed76a612380f95ecb754743a3435/VisioNomicon-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "62b32b907eb74dcf41aa10a93f266c9c3cc28653b660846580d960a416ff5ac9",
"md5": "aeabb7b6f67c3f2cb42ebeaaf86ad56a",
"sha256": "7320016492833ec936f5a0d08503285e67f3ac1ebfb265f8bfcec886264e3874"
},
"downloads": -1,
"filename": "visionomicon-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "aeabb7b6f67c3f2cb42ebeaaf86ad56a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 23468,
"upload_time": "2024-10-05T20:28:52",
"upload_time_iso_8601": "2024-10-05T20:28:52.522590Z",
"url": "https://files.pythonhosted.org/packages/62/b3/2b907eb74dcf41aa10a93f266c9c3cc28653b660846580d960a416ff5ac9/visionomicon-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-05 20:28:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rehanzo",
"github_project": "visionomicon",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "visionomicon"
}
JSON
