144 lines
3.1 KiB
Markdown
144 lines
3.1 KiB
Markdown
# PyNamer
|
|
|
|
PyNamer is a command-line tool that uses AI vision models to generate descriptive filenames for images. It analyzes the content of images and renames them with meaningful, descriptive filenames in snake_case format.
|
|
|
|
## Features
|
|
|
|
- Uses LiteLLM to integrate with various vision-capable LLMs (default: GPT-4 Vision)
|
|
- Configurable via YAML config file
|
|
- Supports multiple image formats (jpg, jpeg, png, gif, webp)
|
|
- Automatically resizes large images before processing (configurable max dimension)
|
|
- Dry-run mode to preview changes without renaming files
|
|
- Handles filename collisions automatically
|
|
- Robust config file discovery (user config, package config, or explicit path)
|
|
|
|
## Installation
|
|
|
|
### Option 1: Install from PyPI (recommended)
|
|
|
|
```bash
|
|
pip install pynamer
|
|
```
|
|
|
|
### Option 2: Install from source
|
|
|
|
1. Clone this repository
|
|
2. Install the package in development mode:
|
|
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
### Set up your API key
|
|
|
|
You need to set up your API key for the vision model:
|
|
|
|
- Set the appropriate environment variable (e.g., `OPENAI_API_KEY`), or
|
|
- Create a custom config file with your API key
|
|
|
|
## Configuration
|
|
|
|
PyNamer uses the following configuration file locations (in order of precedence):
|
|
|
|
1. Custom config file specified with `-c` or `--config` option
|
|
2. User config file at `~/.config/pynamer.yaml` (created automatically on first run)
|
|
3. Default config file included with the package
|
|
|
|
You can customize the following settings:
|
|
|
|
- LLM provider and model
|
|
- API key and endpoint
|
|
- Supported image formats
|
|
- Image resizing parameters (max dimension, output format)
|
|
- Prompt templates for filename generation
|
|
|
|
Example configuration file:
|
|
|
|
```yaml
|
|
# LLM API Configuration
|
|
llm:
|
|
provider: "openai"
|
|
model: "gpt-4-vision-preview"
|
|
api_key: "your-api-key-here"
|
|
max_tokens: 100
|
|
temperature: 0.7
|
|
|
|
# Image Processing
|
|
image:
|
|
supported_formats:
|
|
- ".jpg"
|
|
- ".jpeg"
|
|
- ".png"
|
|
- ".gif"
|
|
- ".webp"
|
|
resize_max_dimension: 1024 # Max width/height before resizing
|
|
resize_format: "JPEG" # Output format for resized images
|
|
|
|
# Prompt Configuration
|
|
prompt:
|
|
system_message: "You are a helpful assistant that generates concise, descriptive filenames..."
|
|
user_message: "Generate a descriptive filename for this image..."
|
|
```
|
|
|
|
## Usage
|
|
|
|
After installation, you can use PyNamer directly from the command line:
|
|
|
|
Basic usage:
|
|
|
|
```bash
|
|
pynamer path/to/image.jpg
|
|
```
|
|
|
|
Process multiple images:
|
|
|
|
```bash
|
|
pynamer image1.jpg image2.png image3.jpg
|
|
```
|
|
|
|
Use a different config file:
|
|
|
|
```bash
|
|
pynamer -c custom_config.yaml image.jpg
|
|
```
|
|
|
|
Preview changes without renaming (dry run):
|
|
|
|
```bash
|
|
pynamer -d image.jpg
|
|
```
|
|
|
|
Enable verbose logging:
|
|
|
|
```bash
|
|
pynamer -v image.jpg
|
|
```
|
|
|
|
## Example
|
|
|
|
Input: `IMG_20230615_123456.jpg` (a photo of a cat sleeping on a window sill)
|
|
|
|
Output: `orange_cat_sleeping_on_sunny_windowsill.jpg`
|
|
|
|
## Development
|
|
|
|
### Building the package
|
|
|
|
```bash
|
|
pip install build
|
|
python -m build
|
|
```
|
|
|
|
### Installing in development mode
|
|
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Python 3.7+
|
|
- LiteLLM
|
|
- PyYAML
|
|
- Access to a vision-capable LLM API (OpenAI, Anthropic, etc.)
|