| Name | image-namer JSON |
| Version |
2.0.3
JSON |
| download |
| home_page | None |
| Summary | Rename image files based on their visual contents using AI vision models. |
| upload_time | 2025-11-05 22:34:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.13 |
| license | MIT License
Copyright (c) 2025 Stacey Vetzal
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
images
renamer
cli
gui
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Image Namer
**Rename image files based on their visual contents using AI vision models.**
[](LICENSE)
[](https://www.python.org/downloads/)
Transform generic filenames like `IMG_2347.jpg` into descriptive names like `golden-retriever-puppy--running-in-park.jpg` using AI vision analysis.
## Features
- 🤖 **AI-powered naming** using Ollama (local) or OpenAI (cloud)
- 🖥️ **Dual interface** - Choose command-line (CLI) or graphical (GUI) workflow
- 🏠 **Local-first** with Ollama for privacy
- ⚡ **Intelligent caching** to avoid redundant API calls
- 🔄 **Idempotent** - won't rename already-suitable files
- 📁 **Batch processing** with recursive folder support
- 📝 **Markdown reference updates** for Obsidian and standard markdown
- 🔍 **Dry-run mode** to preview changes safely (CLI)
- ✏️ **Manual editing** via table double-click (GUI)
- 🎯 **Smart collision handling**
## Quick Start
### Installation
Install Image Namer using [pipx](https://pipx.pypa.io/) for a clean, isolated installation:
```bash
# Install pipx (if needed)
brew install pipx # macOS
# or: python3 -m pip install --user pipx
# CLI only (lightweight)
pipx install image-namer
# With GUI (includes Qt6 interface)
pipx install 'image-namer[gui]'
# Verify installation
image-namer --help # CLI commands
image-namer-ui # Launch GUI (if installed with [gui])
```
**Why pipx?** It installs Python CLI tools in isolated environments, preventing dependency conflicts with other projects.
### Setup AI Provider
Image Namer requires an AI vision model. Choose one:
**Option 1: Ollama (Recommended - Free & Local)**
```bash
# Install from https://ollama.com
ollama pull gemma3:27b
```
**Option 2: OpenAI (Cloud - Requires API Key)**
```bash
export OPENAI_API_KEY='sk-proj-...'
```
### Basic Usage
**Command Line (CLI)**
```bash
# Preview rename (dry-run)
image-namer file photo.jpg
# Apply rename
image-namer file photo.jpg --apply
# Process entire folder
image-namer folder ~/Pictures/screenshots --apply
# Update markdown references
image-namer folder ~/Documents/notes/images --apply --update-refs
```
**Graphical Interface (GUI)**
```bash
# Launch GUI application
image-namer-ui
# Then use the visual workflow:
# 1. Click "Open Folder" to select directory
# 2. Click "Process" to analyze images
# 3. Review/edit names in table (double-click to edit)
# 4. Click "Apply" to rename files
```
## Documentation
📚 **[Full Documentation](https://svetzal.github.io/image-namer/)** (comprehensive guides and reference)
Quick links:
- [Installation Guide](https://svetzal.github.io/image-namer/installation/) - Detailed setup instructions
- [Getting Started](https://svetzal.github.io/image-namer/getting-started/) - Your first rename
- [How-To Guides](https://svetzal.github.io/image-namer/how-to/single-file/) - Step-by-step workflows
- [CLI Reference](https://svetzal.github.io/image-namer/reference/cli-commands/) - Complete command docs
## Development
### Setup
```bash
# Clone repository
git clone https://github.com/svetzal/image-namer.git
cd image-namer
# Install with development dependencies (using uv)
uv venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
uv pip install -e ".[dev,gui]" # Includes GUI for testing
# Or with pip
pip install -e ".[dev,gui]"
```
### Testing
```bash
pytest # Run all tests with coverage
pytest -v --no-cov # Verbose without coverage
flake8 src # Lint code
```
### Documentation
```bash
# Install docs dependencies (included in [dev])
pip install -e ".[dev]"
# Serve docs locally
mkdocs serve
# Build docs locally
mkdocs build
```
**Note**: Documentation is automatically deployed to GitHub Pages when a new release is published. See `docs/GITHUB_PAGES_SETUP.md` for details.
## Requirements
- Python 3.13 or later
- AI provider: Ollama (local) or OpenAI (cloud)
## License
MIT License - see [LICENSE](LICENSE)
## Project Status
🎉 **Version 2.0.0** - Production Ready with GUI
### Complete Features
✅ **Core Functionality**
- Single file and batch folder renaming with AI vision analysis
- Smart pre-flight assessment to skip already-suitable files
- Intelligent caching system (dramatically reduces LLM calls)
- Idempotent operations (won't rename if name already matches content)
✅ **Dual Interface**
- **CLI**: Command-line workflow with dry-run/apply modes
- **GUI**: Qt6 graphical interface with visual preview and editing
✅ **Markdown Integration**
- Automatic reference updates in standard Markdown and Obsidian
- Preserves alt text and aliases
- URL-encoded path handling
✅ **AI Providers**
- Ollama (local, privacy-focused, default)
- OpenAI (cloud-based)
- Easy provider switching via CLI or environment variables
✅ **Developer-Friendly**
- Comprehensive tests with high coverage
- Type-safe with Pydantic models
- Well-documented code and APIs
- Flake8 compliant
### What's Not Included (By Design)
- Video or PDF processing (images only)
- Multi-language filename support (English slugs)
See [CHANGELOG.md](CHANGELOG.md) for detailed release notes.
Raw data
{
"_id": null,
"home_page": null,
"name": "image-namer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "images, renamer, cli, gui",
"author": null,
"author_email": "Stacey Vetzal <stacey@vetzal.com>",
"download_url": "https://files.pythonhosted.org/packages/f0/42/b328b4ecb806076217e4758acd9d50cd320b1affc123ae9b96c496c5eef4/image_namer-2.0.3.tar.gz",
"platform": null,
"description": "# Image Namer\n\n**Rename image files based on their visual contents using AI vision models.**\n\n[](LICENSE)\n[](https://www.python.org/downloads/)\n\nTransform generic filenames like `IMG_2347.jpg` into descriptive names like `golden-retriever-puppy--running-in-park.jpg` using AI vision analysis.\n\n\n\n## Features\n\n- \ud83e\udd16 **AI-powered naming** using Ollama (local) or OpenAI (cloud)\n- \ud83d\udda5\ufe0f **Dual interface** - Choose command-line (CLI) or graphical (GUI) workflow\n- \ud83c\udfe0 **Local-first** with Ollama for privacy\n- \u26a1 **Intelligent caching** to avoid redundant API calls\n- \ud83d\udd04 **Idempotent** - won't rename already-suitable files\n- \ud83d\udcc1 **Batch processing** with recursive folder support\n- \ud83d\udcdd **Markdown reference updates** for Obsidian and standard markdown\n- \ud83d\udd0d **Dry-run mode** to preview changes safely (CLI)\n- \u270f\ufe0f **Manual editing** via table double-click (GUI)\n- \ud83c\udfaf **Smart collision handling**\n\n## Quick Start\n\n### Installation\n\nInstall Image Namer using [pipx](https://pipx.pypa.io/) for a clean, isolated installation:\n\n```bash\n# Install pipx (if needed)\nbrew install pipx # macOS\n# or: python3 -m pip install --user pipx\n\n# CLI only (lightweight)\npipx install image-namer\n\n# With GUI (includes Qt6 interface)\npipx install 'image-namer[gui]'\n\n# Verify installation\nimage-namer --help # CLI commands\nimage-namer-ui # Launch GUI (if installed with [gui])\n```\n\n**Why pipx?** It installs Python CLI tools in isolated environments, preventing dependency conflicts with other projects.\n\n### Setup AI Provider\n\nImage Namer requires an AI vision model. Choose one:\n\n**Option 1: Ollama (Recommended - Free & Local)**\n```bash\n# Install from https://ollama.com\nollama pull gemma3:27b\n```\n\n**Option 2: OpenAI (Cloud - Requires API Key)**\n```bash\nexport OPENAI_API_KEY='sk-proj-...'\n```\n\n### Basic Usage\n\n**Command Line (CLI)**\n```bash\n# Preview rename (dry-run)\nimage-namer file photo.jpg\n\n# Apply rename\nimage-namer file photo.jpg --apply\n\n# Process entire folder\nimage-namer folder ~/Pictures/screenshots --apply\n\n# Update markdown references\nimage-namer folder ~/Documents/notes/images --apply --update-refs\n```\n\n**Graphical Interface (GUI)**\n```bash\n# Launch GUI application\nimage-namer-ui\n\n# Then use the visual workflow:\n# 1. Click \"Open Folder\" to select directory\n# 2. Click \"Process\" to analyze images\n# 3. Review/edit names in table (double-click to edit)\n# 4. Click \"Apply\" to rename files\n```\n\n## Documentation\n\n\ud83d\udcda **[Full Documentation](https://svetzal.github.io/image-namer/)** (comprehensive guides and reference)\n\nQuick links:\n- [Installation Guide](https://svetzal.github.io/image-namer/installation/) - Detailed setup instructions\n- [Getting Started](https://svetzal.github.io/image-namer/getting-started/) - Your first rename\n- [How-To Guides](https://svetzal.github.io/image-namer/how-to/single-file/) - Step-by-step workflows\n- [CLI Reference](https://svetzal.github.io/image-namer/reference/cli-commands/) - Complete command docs\n\n## Development\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/svetzal/image-namer.git\ncd image-namer\n\n# Install with development dependencies (using uv)\nuv venv\nsource .venv/bin/activate # Windows: .venv\\Scripts\\activate\nuv pip install -e \".[dev,gui]\" # Includes GUI for testing\n\n# Or with pip\npip install -e \".[dev,gui]\"\n```\n\n### Testing\n\n```bash\npytest # Run all tests with coverage\npytest -v --no-cov # Verbose without coverage\nflake8 src # Lint code\n```\n\n### Documentation\n\n```bash\n# Install docs dependencies (included in [dev])\npip install -e \".[dev]\"\n\n# Serve docs locally\nmkdocs serve\n\n# Build docs locally\nmkdocs build\n```\n\n**Note**: Documentation is automatically deployed to GitHub Pages when a new release is published. See `docs/GITHUB_PAGES_SETUP.md` for details.\n\n## Requirements\n\n- Python 3.13 or later\n- AI provider: Ollama (local) or OpenAI (cloud)\n\n## License\n\nMIT License - see [LICENSE](LICENSE)\n\n## Project Status\n\n\ud83c\udf89 **Version 2.0.0** - Production Ready with GUI\n\n### Complete Features\n\u2705 **Core Functionality**\n- Single file and batch folder renaming with AI vision analysis\n- Smart pre-flight assessment to skip already-suitable files\n- Intelligent caching system (dramatically reduces LLM calls)\n- Idempotent operations (won't rename if name already matches content)\n\n\u2705 **Dual Interface**\n- **CLI**: Command-line workflow with dry-run/apply modes\n- **GUI**: Qt6 graphical interface with visual preview and editing\n\n\u2705 **Markdown Integration**\n- Automatic reference updates in standard Markdown and Obsidian\n- Preserves alt text and aliases\n- URL-encoded path handling\n\n\u2705 **AI Providers**\n- Ollama (local, privacy-focused, default)\n- OpenAI (cloud-based)\n- Easy provider switching via CLI or environment variables\n\n\u2705 **Developer-Friendly**\n- Comprehensive tests with high coverage\n- Type-safe with Pydantic models\n- Well-documented code and APIs\n- Flake8 compliant\n\n### What's Not Included (By Design)\n- Video or PDF processing (images only)\n- Multi-language filename support (English slugs)\n\nSee [CHANGELOG.md](CHANGELOG.md) for detailed release notes.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Stacey Vetzal\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Rename image files based on their visual contents using AI vision models.",
"version": "2.0.3",
"project_urls": {
"Homepage": "https://github.com/svetzal/image-namer",
"Issues": "https://github.com/svetzal/image-namer/issues"
},
"split_keywords": [
"images",
" renamer",
" cli",
" gui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "effd18285289de563a1595b4bd266706c54e4ef91008ce5176b7aeadc89bb2a0",
"md5": "890a4ddf95826ca21be268df22c25078",
"sha256": "12a941236a2cebe8b552afc6c415bb98a15a41491b545825dfe0cbd6c0bb9738"
},
"downloads": -1,
"filename": "image_namer-2.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "890a4ddf95826ca21be268df22c25078",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 50164,
"upload_time": "2025-11-05T22:34:10",
"upload_time_iso_8601": "2025-11-05T22:34:10.404737Z",
"url": "https://files.pythonhosted.org/packages/ef/fd/18285289de563a1595b4bd266706c54e4ef91008ce5176b7aeadc89bb2a0/image_namer-2.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f042b328b4ecb806076217e4758acd9d50cd320b1affc123ae9b96c496c5eef4",
"md5": "f06d6113392400afbcdc5bc2668c71de",
"sha256": "de693e5436d2b8e58713ac86edb5a9a2c551c36fe2a995447033bc3e01ce57c2"
},
"downloads": -1,
"filename": "image_namer-2.0.3.tar.gz",
"has_sig": false,
"md5_digest": "f06d6113392400afbcdc5bc2668c71de",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 41151,
"upload_time": "2025-11-05T22:34:11",
"upload_time_iso_8601": "2025-11-05T22:34:11.737762Z",
"url": "https://files.pythonhosted.org/packages/f0/42/b328b4ecb806076217e4758acd9d50cd320b1affc123ae9b96c496c5eef4/image_namer-2.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-05 22:34:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "svetzal",
"github_project": "image-namer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "image-namer"
}
