docs: add comprehensive feature documentation
Document all implemented and planned features: - Current features with implementation status - Planned features organized by priority - Technical architecture details - Keyboard shortcuts reference - Contributing guidelines for new features
This commit is contained in:
mow
parent
00425fcf4b
commit
ffcca4dbfe
1 changed files with 207 additions and 0 deletions
207
docs/features.md
207
docs/features.md
|
|
@ -0,0 +1,207 @@
|
|||
# Noctua Features
|
||||
|
||||
This document describes the implemented and planned features of Noctua, a modern image viewer for the COSMIC desktop environment.
|
||||
|
||||
## Current Features
|
||||
|
||||
### Document Support
|
||||
|
||||
#### Raster Images ✅
|
||||
- **Formats**: PNG, JPEG, GIF, BMP, TIFF, WebP, and all formats supported by `image-rs`
|
||||
- **Capabilities**:
|
||||
- Full pixel-perfect rendering at 100% zoom
|
||||
- Lossless transformations (rotate, flip)
|
||||
- Real-time transformation preview
|
||||
- EXIF metadata extraction
|
||||
|
||||
#### Vector Graphics ✅
|
||||
- **Formats**: SVG
|
||||
- **Capabilities**:
|
||||
- High-quality rendering via `resvg`
|
||||
- Scalable display without quality loss
|
||||
- Metadata extraction
|
||||
- ⚠️ Note: Transformations not yet implemented for vector documents
|
||||
|
||||
#### Portable Documents ✅
|
||||
- **Formats**: PDF
|
||||
- **Capabilities**:
|
||||
- First page rendering
|
||||
- Basic transformations on rendered page
|
||||
- ⚠️ Note: Multi-page navigation not yet implemented
|
||||
|
||||
### Navigation
|
||||
|
||||
#### Folder Navigation ✅
|
||||
- **Automatic folder scanning**: When opening an image, all supported images in the same folder are indexed
|
||||
- **Quick navigation**:
|
||||
- Arrow keys (Left/Right) to navigate between images
|
||||
- Footer displays current position (e.g., "3 / 42")
|
||||
- Seamless transitions between images
|
||||
|
||||
#### File Opening ✅
|
||||
- **Command-line arguments**: Open images directly from terminal
|
||||
- **Default directory**: Configurable starting location (defaults to XDG Pictures)
|
||||
- ⚠️ File dialog not yet implemented
|
||||
|
||||
### View Controls
|
||||
|
||||
#### Zoom ✅
|
||||
- **Mouse wheel**: Zoom in/out centered on cursor position
|
||||
- **Keyboard shortcuts**:
|
||||
- `+` or `=` - Zoom in
|
||||
- `-` - Zoom out
|
||||
- `1` - Reset to 100% (Actual Size)
|
||||
- `f` - Fit to window
|
||||
- **View modes**:
|
||||
- **Fit**: Automatically scales image to fit window while preserving aspect ratio
|
||||
- **Actual Size**: Displays image at 100% (1:1 pixel mapping)
|
||||
- **Custom**: Any zoom level from 10% to 2000%
|
||||
- **Footer display**: Real-time zoom percentage or "Fit" indicator
|
||||
|
||||
#### Pan ✅
|
||||
- **Mouse drag**: Click and drag to pan around zoomed images
|
||||
- **Keyboard shortcuts**: `Ctrl + Arrow Keys` for precise panning
|
||||
- **Smart boundaries**: Pan is automatically limited to image boundaries
|
||||
- **Auto-center**: Images smaller than viewport are automatically centered
|
||||
|
||||
#### Bidirectional State Sync ✅
|
||||
- Mouse interactions update keyboard/button controls
|
||||
- Keyboard/button controls update mouse interaction state
|
||||
- No conflicts between input methods
|
||||
|
||||
### Transformations
|
||||
|
||||
#### Image Manipulation ✅
|
||||
- **Rotate**:
|
||||
- `r` - Rotate 90° clockwise
|
||||
- `Shift + r` - Rotate 90° counter-clockwise
|
||||
- Toolbar buttons available
|
||||
- **Flip**:
|
||||
- `h` - Flip horizontally (mirror)
|
||||
- `v` - Flip vertically
|
||||
- Toolbar buttons available
|
||||
- **Lossless operations**: All transformations preserve original image quality
|
||||
- **Real-time preview**: Changes are immediately visible
|
||||
|
||||
### User Interface
|
||||
|
||||
#### COSMIC Integration ✅
|
||||
- **Native COSMIC design**: Follows COSMIC desktop design language
|
||||
- **Theme support**: Automatically adapts to system light/dark theme
|
||||
- **Header toolbar**:
|
||||
- Navigation controls (Previous/Next)
|
||||
- Transformation buttons (Rotate, Flip)
|
||||
- Information panel toggle
|
||||
- **Footer bar**:
|
||||
- Zoom controls with buttons
|
||||
- Current zoom level display
|
||||
- Image dimensions
|
||||
- Navigation position counter
|
||||
|
||||
#### Panels
|
||||
- **Properties panel** ✅:
|
||||
- Image metadata display
|
||||
- File information
|
||||
- Toggle with `i` key or toolbar button
|
||||
- **Navigation panel** (Left sidebar):
|
||||
- Toggle with `n` key or toolbar button
|
||||
- ⚠️ Content not yet implemented
|
||||
|
||||
#### Keyboard Shortcuts ✅
|
||||
Full keyboard-driven workflow:
|
||||
- Navigation: `←` `→`
|
||||
- Zoom: `+` `-` `1` `f`
|
||||
- Pan: `Ctrl + ←` `Ctrl + →` `Ctrl + ↑` `Ctrl + ↓`
|
||||
- Transform: `r` `Shift+r` `h` `v`
|
||||
- Panels: `i` `n`
|
||||
|
||||
### Configuration
|
||||
|
||||
#### Persistent Settings ✅
|
||||
- **Panel states**: Remembers which panels were open
|
||||
- **Default directory**: Customizable starting location
|
||||
- **Settings location**: `~/.config/noctua/config.toml`
|
||||
|
||||
### Technical Features
|
||||
|
||||
#### Architecture ✅
|
||||
- **Clean separation**: View layer agnostic to document format
|
||||
- **Polymorphic documents**: Single `DocumentContent` interface for all formats
|
||||
- **Efficient rendering**: Leverages COSMIC's iced renderer
|
||||
- **Type-safe transformations**: Compile-time guarantees for image operations
|
||||
|
||||
#### Performance ✅
|
||||
- **Lazy loading**: Images loaded on-demand
|
||||
- **Efficient folder scanning**: Fast directory traversal
|
||||
- **Minimal memory footprint**: Only active document kept in memory
|
||||
- **Smooth zooming**: Hardware-accelerated rendering
|
||||
|
||||
## Planned Features
|
||||
|
||||
### High Priority
|
||||
|
||||
#### File Operations ⏳
|
||||
- File dialog integration (OpenPath message prepared)
|
||||
- Save transformed images
|
||||
- Copy/Move/Delete operations
|
||||
- Drag-and-drop support
|
||||
|
||||
#### Multi-page Documents ⏳
|
||||
- PDF page navigation
|
||||
- Multi-page TIFF support
|
||||
- Page thumbnails
|
||||
|
||||
#### Error Handling ⏳
|
||||
- User-friendly error messages (ShowError/ClearError prepared)
|
||||
- Graceful handling of corrupted files
|
||||
- Recovery suggestions
|
||||
|
||||
### Medium Priority
|
||||
|
||||
#### Vector Document Transformations ⏳
|
||||
- Rotate SVG files
|
||||
- Flip SVG files
|
||||
- Transform preservation on save
|
||||
|
||||
#### Enhanced Navigation
|
||||
- Thumbnail strip
|
||||
- Grid view for folder contents
|
||||
- Quick jump to file
|
||||
|
||||
#### Slideshow Mode
|
||||
- Auto-advance timer
|
||||
- Configurable intervals
|
||||
- Fullscreen support
|
||||
|
||||
### Low Priority
|
||||
|
||||
#### Advanced Editing
|
||||
- Crop tool (message prepared)
|
||||
- Scale/Resize tool (message prepared)
|
||||
- Basic color adjustments
|
||||
|
||||
#### Batch Operations
|
||||
- Bulk transformations
|
||||
- Format conversion
|
||||
- Batch export
|
||||
|
||||
#### Metadata Editing
|
||||
- EXIF data modification
|
||||
- Comment annotations
|
||||
- Tag management
|
||||
|
||||
## Feature Status Legend
|
||||
|
||||
- ✅ **Implemented**: Fully functional and tested
|
||||
- ⏳ **Planned**: Design complete, implementation pending
|
||||
- ⚠️ **Partial**: Basic functionality exists, enhancements needed
|
||||
- 🔄 **In Progress**: Currently being developed
|
||||
|
||||
## Contributing
|
||||
|
||||
Features marked as "Planned" have their message handlers already prepared in the codebase. Look for:
|
||||
- `OpenPath`, `RefreshMetadata` in `src/app/message.rs`
|
||||
- `ToggleCropMode`, `ToggleScaleMode` in transformation handlers
|
||||
- Comments marked with `TODO:` in document implementations
|
||||
|
||||
Pull requests welcome! See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
|
||||
Loading…
Add table
Add a link
Reference in a new issue