code/configs/preprocessing.yaml

# SOTA preprocessing config (v1.0)
# Source: 2024-2026 literature review (cuneiform + historical OCR)
# Applied + recipe-only steps

version: "1.0"
pipeline_hash_algorithm: "sha256"  # config + code version hash

# ========== Quality gating (OFFLINE, filter-only) ==========
quality_gates:
  blur_laplacian_min_variance: 100.0      # Pech-Pacheco 2000
  exposure_mean_min: 20.0                  # min brightness (0-255)
  exposure_mean_max: 235.0                 # max brightness
  contrast_std_min: 15.0                   # min contrast
  resolution_min_w: 32
  resolution_min_h: 32
  policy: "soft_exclude"                   # soft: training'de skip, eval'de tut

# ========== Geometric normalization ==========
geometric:
  letterbox:
    target_size: 224                        # DINOv3 / ResNet standardı
    margin_ratio: 0.10                      # DeepScribe varsayılanı (0.08-0.12)
    fill_mode: "median_border"              # pad color = tablet surface median
  rotation_canonicalization:
    enabled: true
    candidate_angles: [0, 90, 180, 270]    # view-based
    use_view_hint: true                    # tablet_view_fold hint
  deskew:
    enabled: false                          # tablet'ler genelde düz
    
# ========== Image enhancement ==========
enhancement:
  clahe:
    enabled: true
    clip_limit: 2.5                         # 2.0-3.0 arası (Bui/Chkeir 2024)
    tile_grid: [8, 8]
    color_space: "LAB"                      # L-channel on LAB
    conditional: true                       # sadece blur/dark ise
  gamma_correction:
    enabled: true
    gamma: 1.2
    conditional: true
  unsharp_mask:
    enabled: false                          # agresif, detaile zarar verir
  denoising:
    enabled: false                          # NAFNet recipe (offline pre-compute için)
    method: "nafnet"                        # "nafnet" | "nlm" | "bm3d"

# ========== Binarization (auxiliary channel) ==========
binarization:
  enabled: false                            # opsiyonel auxiliary kanal
  method: "sauvola"                         # "sauvola" | "otsu" | "wolf" | "sauvola_dl"
  sauvola:
    window_size: 25
    k: 0.2
    
# ========== Background-aware crop ==========
crop:
  bbox_expansion_ratio: 0.12                # DeepScribe önerisi
  background_fill: "median_border"          # crop dışarı taşarsa
  preserve_aspect_ratio: true

# ========== Normalization (pixel values) ==========
normalization:
  strategy: "dataset_specific"              # "imagenet" | "dataset_specific" | "none"
  mean: null                                # offline pass ile hesaplanacak
  std: null
  channels: 3                               # RGB; 4 ile auxiliary MSII/binarization

# ========== Augmentation (train-time, offline pre-compute değil) ==========
augment_train:
  elastic_transform:
    enabled: true
    alpha: 40.0
    sigma: 6.0
    alpha_affine: 8.0
    p: 0.5
  grid_distortion:
    enabled: true
    num_steps: 5
    distort_limit: 0.15
    p: 0.3
  morphological:
    enabled: true
    ops: ["erode", "dilate"]
    kernel_size: 2
    p: 0.3
  color_jitter:
    enabled: true
    brightness: 0.2
    contrast: 0.2
    saturation: 0.1
    p: 0.5
  horizontal_flip:
    enabled: false                          # sign orientation önemli
  mixup:
    enabled: true                           # tail sınıflar için feature-space
    alpha: 0.5
  cutmix:
    enabled: false                          # bbox context kaybettirir

# ========== Cuneiform-specific (SOTA recipe, offline GPU) ==========
cuneiform_specific:
  msii_proxy:
    enabled: true                           # Multi-scale LoG (cheap alternative)
    sigmas: [1.0, 2.0, 4.0, 8.0]
    channel: "auxiliary"                    # concat RGB ile 4. kanal
  illumination_augment:
    enabled: false                          # Recipe only, Blender/3D gerekir
    n_lights: 8
    method: "blender_render"
  super_resolution:
    enabled: false                          # Real-ESRGAN offline pass
    method: "real_esrgan_x2"
    min_width_threshold: 256

# ========== Cache ==========
cache:
  enabled: true
  format: "webdataset_jpeg"                 # "webdataset_jpeg" | "parquet_bytes"
  jpeg_quality: 90
  shard_size_mb: 1024
  output_dir: "datasets/streaming/preprocessed_224"

# ========== Inference-only ==========
inference:
  tta: false                                # test-time augmentation
  multi_scale: [224, 256, 288]              # multi-scale ensemble
  center_crop: true