180 lines
No EOL
4.4 KiB
Markdown
180 lines
No EOL
4.4 KiB
Markdown
# PNG Metadata Editor v2.3.0
|
|
|
|
A graphical tool for viewing and editing metadata in PNG files with an intuitive image browser interface.
|
|
|
|
|
|
|
|
## Features
|
|
|
|
### Core Features
|
|
- View all metadata fields (tEXt, zTXt, iTXt chunks) in PNG files
|
|
- Add, edit, and delete metadata fields
|
|
- Copy metadata values to clipboard
|
|
- Visual indication of unsaved changes
|
|
- Pretty-print JSON values in editor (auto-flattens on save)
|
|
|
|
### Image Browser
|
|
- Browse directories with thumbnail previews
|
|
- Auto-scroll to selected images
|
|
- Trackpad and mousewheel scrolling support
|
|
- Smooth navigation between multiple files
|
|
|
|
### User Interface
|
|
- Automatic dark mode detection (macOS, Windows, Linux)
|
|
- Adaptive canvas background based on system theme
|
|
- Unicode support throughout UI
|
|
- Resizable panes for optimal workflow
|
|
|
|
### Technical Improvements
|
|
- Smart JSON handling: displays formatted, saves flattened
|
|
- Proper file handle management for reliable multi-file loading
|
|
- Enhanced scroll region updates for smooth browsing
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.6+
|
|
- Tkinter (usually included with Python)
|
|
|
|
### Dependencies
|
|
|
|
Install required packages using pip:
|
|
|
|
```bash
|
|
pip install pillow
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Workflow
|
|
|
|
1. Run the application:
|
|
```bash
|
|
python png-meta-editor.py
|
|
```
|
|
|
|
2. **Browse Directory**: Click "Browse Directory" to load thumbnails from a folder
|
|
3. **Select Image**: Click any thumbnail to load its metadata
|
|
4. **View Metadata**: See all fields in the tree view with preview
|
|
5. **Edit Fields**:
|
|
- Double-click or use "Edit Field" to modify values
|
|
- JSON values display formatted but save flattened
|
|
6. **Save Changes**: Click "Save Changes" to write metadata back to file
|
|
|
|
### Keyboard Shortcuts
|
|
|
|
- **Double-click** on tree item to edit
|
|
- **Enter/Escape** in dialogs to confirm/cancel
|
|
|
|
### Dark Mode
|
|
|
|
The application automatically detects your system theme:
|
|
- **macOS**: Reads `AppleInterfaceStyle` setting
|
|
- **Windows**: Reads personalization registry settings
|
|
- **Linux**: Checks GTK theme preferences
|
|
|
|
## Building for Distribution
|
|
|
|
### Using build.py (Recommended)
|
|
|
|
1. First install the required build tools:
|
|
```bash
|
|
pip install pyinstaller
|
|
```
|
|
|
|
2. Build the application for your platform:
|
|
```bash
|
|
python build.py
|
|
```
|
|
|
|
3. The resulting executable will be in the `dist/` directory
|
|
|
|
### Manual PyInstaller Commands
|
|
|
|
#### Windows
|
|
```bash
|
|
pyinstaller --name="PNG Metadata Editor" \
|
|
--windowed \
|
|
--onefile \
|
|
--icon=AppIcon.ico \
|
|
--version-file version.txt \
|
|
png-meta-editor.py
|
|
```
|
|
|
|
#### macOS
|
|
```bash
|
|
pyinstaller --name="PNG Metadata Editor" \
|
|
--windowed \
|
|
--onefile \
|
|
--icon=AppIcon.icns \
|
|
--version-file version.txt \
|
|
png-meta-editor.py
|
|
```
|
|
|
|
#### Linux
|
|
```bash
|
|
pyinstaller --name="PNG Metadata Editor" \
|
|
--windowed \
|
|
--onefile \
|
|
png-meta-editor.py
|
|
```
|
|
|
|
## Required Files
|
|
|
|
For building, you'll need:
|
|
- `version.txt` (for version information)
|
|
- `AppIcon.ico` (Windows icon)
|
|
- `AppIcon.icns` (Mac icon)
|
|
- `requirements.txt` (for dependencies)
|
|
|
|
## Technical Details
|
|
|
|
### JSON Handling
|
|
|
|
The editor intelligently handles JSON metadata:
|
|
- **Display**: Pretty-printed with indentation for readability
|
|
- **Storage**: Automatically flattened to single line to preserve original format
|
|
- **Example**:
|
|
```json
|
|
// What you see in editor:
|
|
{
|
|
"prompt": "a cat",
|
|
"steps": 20
|
|
}
|
|
|
|
// What gets saved:
|
|
{"prompt":"a cat","steps":20}
|
|
```
|
|
|
|
### File Management
|
|
|
|
- Proper file handle release after reading metadata
|
|
- Supports loading multiple files sequentially without issues
|
|
- Thumbnail caching for smooth browsing experience
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.
|
|
|
|
## Author
|
|
|
|
Robert Tusa
|
|
robert@tusa.at
|
|
|
|
## Version History
|
|
|
|
### v2.3.0 (2026-01-07) - Major UI Update
|
|
- Added image browser with thumbnail previews
|
|
- Implemented dark mode detection for all platforms
|
|
- Added trackpad/mousewheel scrolling support
|
|
- Smart JSON flattening (preserves original format)
|
|
- Fixed file loading issues with proper handle management
|
|
- Enhanced scroll region updates
|
|
- Unicode support in UI elements
|
|
|
|
### v1.0.0 (2026-01-05) - Initial Release
|
|
- Basic metadata viewing and editing
|
|
- Tree view with detail pane
|
|
- Add, edit, delete operations
|
|
- JSON pretty-printing |