imajviewer/docs/plan-crop-save.md

# Plan — Crop Save (görünen alanı kaydet)

Tarih: 2026-10-11 · Versiyon: 1.4.0 · Durum: UYGULANDI (2026-10-11) — manual test + commit/push bekleniyor

## Not — Uygulama Sırası
- `image` v3 kullanılamadı: `msix 3.18.0` `image ^4.0.0` gerektiriyor → v4 async API kullanıldı
  (`decodeImage` Uint8List ile, `copyCrop(x:,y:,width:,height:)`, `JpegEncoder(quality:90)`,
  `bakeOrientation`, pixel kanalları `r/g/b/a`).
- v4'te renk matrisi filtresi yok → matris `crop_save_service.dart:_applyMatrix` ile elle
  uygulandı (aynı 0-255 alanı).
- Boyut okuma ayrı descriptor yerine tam decode (`load()`) üzerinden yapılıyor.

## Gereksinim + Kararlar
- Pencerenin görünen kısmı (image canvas viewport'u) → **orijinal çözünürlükte** crop
- JPEG **quality 90**
- Dosya adı: orijinal ismin sonuna **saat only** eki → `resim.jpg` → `resim_143025.jpg`
- **Çakışma:** dosya zaten varsa yazı YAPILMAZ, uyarı gösterilir (mevcut dosya korunur)
- **Renk efektleri:** kayda **GÖMÜLÜR** (contrast/saturation/brightness, ekrandaki gibi)
- **Rotasyon aktifken:** yapılsın — görünür bölgeyi saran dikdörtgen (bounding box) kaydedilir
- Title bar: Save butonu minimize'in SOLUNDA (sıralama: **save · minimize · x**)
- Klavye: **Ctrl+S** de tetikler

## Mimari Analiz

### 1) Görünen alan → kaynak piksel eşlemesi
`image_canvas.dart` render zinciri: `Transform(translate(_tx,_ty) scale(_sc))` içinde
opsiyonel `Transform(rotate(_angle), vpCenter)` → `Image(fit: cover|contain)`.

Canvas lokal koordinatındaki bir nokta `p` için geri dönüş:
1. `q = (p - (tx,ty)) / sc`
2. `_angle != 0` ise `r` = `q`'yi vpCenter ekseninde `-angle` kadar döndür (yoksa `r = q`)
3. **cover** (`_isFilled`): `k = max(vpW/iw, vpH/ih)`; **contain**: `k = min(vpW/iw, vpH/ih)`;
   her ikisinde de `ox=(vpW-iw*k)/2`, `oy=(vpH-ih*k)/2` → `src = ((r.x-ox)/k, (r.y-oy)/k)`
4. Viewport'un 4 köşesi → `src` uzayda → min/max bounding box → `[0,iw]×[0,ih]`'a clamp → int
5. Rotasyonlu durumda bounding box, ekranda görünür bölgeyi kapsayan dikdörtgendir
   (çıkış aspect/boyutu pencereden farklı olabilir — onaylı davranış)

- `iw,ih` = **gerçek** dosya boyutu (descriptor ile). `_imageSize` downsample'lı (2048)
  olabilir → eşlemede kullanılmaz.
- Görünen alan = **tamamı canvas viewport** (title bar 24px bindirilmiş overlay, görsel
  arkasında görünüyor → kesime dahil).

### 2) Encode zinciri (yeni bağımlılık: `image` ^4.x, saf Dart)
```
File → img.decodeImage(bytes, keepOrientation: true)
     → img.cropRect(rect)
     → aktif renk matrisi var ise img.ColorMatrixFilter(mat4x5).applyTo(crop)
     → img.encodeJpeg(crop, quality: 90)
     → hedef yol var ise → uyarı (yazılmaz); yoksa File.writeAsBytes
```
- **Renk matrisi:** `image_canvas.dart`'daki mevcut `_buildCombinedFilter()` 4x5 matrisi
  (contrast×brightness×saturation) aynı zamanda `ColorFilter.matrix` olarak kullanılıyor.
  State'e `List<double>? activeColorMatrix` getter'ı eklenir (filtre identity ise null).
  Flutter ve `image` paketi aynı 4x5 row-major / 0-255 alanı kullanır → matris aynen
  taşınır, yeniden türetilmez.
- **Tuzak — EXIF yönü:** Flutter engine JPEG'lerde EXIF orientation uygular;
  `keepOrientation: true` verilmezse 90° döndürülmüş fotoğraflarda crop yanlış yerden
  kesilir. Test listesinde zorunlu.
- **WBMP:** `image` WBMP çözer (uygulama destekliyor); decode hatası → "desteklenmiyor"
  mesajı, çökme yok.

### 3) Bileşenler
| Dosya | Değişiklik |
|---|---|
| `pubspec.yaml` | `image: ^4.x`; versiyon `1.4.0+8` |
| `lib/services/crop_save_service.dart` | **YENİ** — `imageSize(path)` (descriptor), `saveCrop({srcPath, rect, matrix, outPath})`, ad üretimi (`_HHmmss`), çakışma kontrolü (exists → uyarı), hata mesajları |
| `lib/widgets/image_canvas.dart` | State → `ImageCanvasState` (public); `Rect? cropSourceRect(int w, int h)`; `List<double>? activeColorMatrix` getter |
| `lib/screens/viewer_screen.dart` | `GlobalKey<ImageCanvasState>`, `_cropSave()`, sonuç geri bildirimi (kısa overlay/Snackbar: yol veya hata) |
| `lib/widgets/custom_title_bar.dart` | `onSaveCrop` param; save ikonu minimize'in solunda; mevcut `_BarButton` stili (hover kırmızı) |
| `lib/shortcuts/app_shortcuts.dart` | `Ctrl+S` → crop save (callback param ile) |
| `lib/l10n/app_{en,tr}.arb` | `saveCrop` (tooltip), `cropSaved`, `cropFailed`, `cropFileExists`, `cropUnsupported` + `shortcutsList` güncelleme; `flutter gen-l10n` |
| `CHANGELOG.md` | `[1.4.0]` |

### 4) Etkileşim
- Buton yalnızca görsel yüklüyken aktif (yoksa null → pas geçilir).
- Başarıda: kaydedilen tam yol gösterilir; hata/çakışmada: hata metni.
- Tam decode kayıt anında, tek seferlik (downsample swap ile ilişkisi yok).

## Sınır Durumları
1. Görsel yok → buton pasif, Ctrl+S no-op
2. Crop rect boş/degenerate → hata mesajı
3. Yazılamayan klasör → hata mesajı, çökme yok
4. **Çakışma: dosya var → yazılmaz, uyarı** (karar)
5. WBMP/decode hatası → `cropUnsupported`
6. Rotasyonlu bounding box (karar: kaydedilir)
7. Büyük görsellerde tam decode RAM'i — tek seferlik, kabul edilebilir

## Doğrulama
1. `flutter analyze` (otomatik izinli)
2. `flutter build linux --debug` + `./install.sh` (otomatik izinli)
3. Kullanıcı manuel test: fit/cover, zoom, pan, rotasyon + kaydet, renk efektleri + kaydet,
   EXIF 90° görsel, WBMP, çakışan isim (uyarı + dosya korunur), salt okunur dizin
4. Commit + push: yalnızca senin komutunla

## Kapsam Dışı
- Kullanıcı alanı seçerek crop (her zaman "görünen bölge")
- PNG/özel format seçimi (sabit JPEG q90)
- Gitea CI release / tag (senin komutunla)