Update README.md

README.md

@@ -1,3 +1,490 @@
 ---
-license: apache-2.0
+library_name: onnx
+tags:
+  - computer-vision
+  - image-enhancement
+  - photo-retouching
+  - computational-photography
+  - color-grading
+  - onnx
+  - mobile
+  - lightweight
+  - multi-task-learning
+datasets:
+  - Phitran21/adaptive-photo-retouching-6style
 ---
+
+# AdaptivePhotoNet
+
+**AdaptivePhotoNet** is a lightweight, scene-aware neural network for
+automatic photo retouching.
+
+Instead of generating a new image pixel-by-pixel, the model analyzes a
+low-resolution preview of the photograph and predicts a compact
+**21-dimensional retouching recipe** that can be applied to the original
+full-resolution image by a deterministic image-processing pipeline.
+
+The model also predicts **10 scene attributes** to provide auxiliary
+scene understanding.
+
+AdaptivePhotoNet contains **5,876,943 parameters** and supports six
+retouching styles:
+
+- Natural
+- Vivid
+- Cinema
+- Portrait
+- Film
+- Moody
+
+The model is exported to **ONNX** and designed with lightweight desktop,
+mobile, and edge inference in mind.
+
+---
+
+## Model Concept
+
+AdaptivePhotoNet separates **visual understanding** from
+**full-resolution image processing**.
+
+```text
+                     ┌─────────────────┐
+                     │  Original Image │
+                     └────────┬────────┘
+                              │
+                       resize / preview
+                              │
+                              ▼
+                    ┌──────────────────┐
+                    │ RGB 224 × 224    │
+                    └────────┬─────────┘
+                             │
+             ┌───────────────┴───────────────┐
+             │                               │
+        Image Features                  Style ID
+             │                         0 ... 5
+             └───────────────┬───────────────┘
+                             ▼
+                    ┌──────────────────┐
+                    │ AdaptivePhotoNet │
+                    │  5.88M params    │
+                    └────────┬─────────┘
+                             │
+                  ┌──────────┴──────────┐
+                  ▼                     ▼
+          21D Retouch Recipe      10 Scene Scores
+                  │
+                  ▼
+        Deterministic Retouching
+                Pipeline
+                  │
+                  ▼
+       Full-Resolution Output Image
+
+The neural network therefore does not need to reconstruct the full-resolution photograph.
+
+It predicts how the photograph should be adjusted, while the final rendering is performed by conventional image-processing operations.
+
+This design has several practical advantages:
+
+low neural-network inference cost;
+
+processing is independent of the original image resolution at the model stage;
+
+deterministic full-resolution rendering;
+
+compact ONNX deployment;
+
+interpretable adjustment parameters;
+
+selectable photographic styles;
+
+suitable for mobile and edge applications.
+
+
+
+---
+
+Model Specifications
+
+Property	Value
+
+Model	AdaptivePhotoNet
+Parameters	5,876,943
+Model input resolution	224 × 224
+Image format	RGB
+Tensor layout	NCHW
+Image dtype	float32
+Image range	[0.0, 1.0]
+Style input	int64
+Number of styles	6
+Recipe output	21 dimensions
+Scene output	10 dimensions
+Runtime format	ONNX
+
+
+
+---
+
+Inputs
+
+Image
+
+name: image
+shape: [1, 3, 224, 224]
+dtype: float32
+layout: NCHW
+color: RGB
+range: 0.0 - 1.0
+
+The original photograph should be converted to RGB, resized to 224 × 224, converted to float32, normalized to [0, 1], and arranged in NCHW format.
+
+The 224 × 224 image is used for analysis only.
+
+The final retouching operations can be applied separately to the original full-resolution photograph.
+
+Style
+
+name: style_id
+shape: [1]
+dtype: int64
+
+ID	Style
+
+0	Natural
+1	Vivid
+2	Cinema
+3	Portrait
+4	Film
+5	Moody
+
+
+Changing style_id instructs the same model to predict a different retouching direction for the input photograph.
+
+
+---
+
+Outputs
+
+AdaptivePhotoNet produces two outputs.
+
+1. Retouching Recipe
+
+shape: [1, 21]
+
+The 21-dimensional vector describes the photographic adjustments that should be applied by the retouching engine.
+
+Linear Parameters
+
+Dimensions 0–16 represent:
+
+Dim	Parameter	Range
+
+0	Exposure EV	-2.0 → 2.0
+1	Temperature	-1.0 → 1.0
+2	Tint	-1.0 → 1.0
+3	Shadows	-1.0 → 1.0
+4	Highlights	-1.0 → 1.0
+5	Contrast	-1.0 → 1.0
+6	Tone Curve 0	0.0 → 1.0
+7	Tone Curve 1	0.0 → 1.0
+8	Tone Curve 2	0.0 → 1.0
+9	Tone Curve 3	0.0 → 1.0
+10	Tone Curve 4	0.0 → 1.0
+11	Shadow Tone Strength	0.0 → 0.3
+12	Highlight Tone Strength	0.0 → 0.3
+13	Saturation	-1.0 → 1.0
+14	Vibrance	-1.0 → 1.0
+15	Fade	0.0 → 1.0
+16	Vignette	0.0 → 1.0
+
+
+Hue Parameters
+
+Hue is represented circularly using sine/cosine pairs rather than a single scalar value.
+
+17, 18 → shadow_tone_hue    [sin, cos]
+19, 20 → highlight_tone_hue [sin, cos]
+
+This avoids the discontinuity that occurs when representing circular hue values directly near the angle boundary.
+
+The complete interpretation is defined in:
+
+recipe_schema.json
+
+
+---
+
+2. Scene Probabilities
+
+shape: [1, 10]
+
+The auxiliary scene head predicts ten visual attributes:
+
+Index	Scene Attribute
+
+0	Human
+1	Face Visible
+2	Skin Visible
+3	Portrait
+4	Indoor
+5	Outdoor
+6	Night
+7	Low Light
+8	Backlit
+9	High Dynamic Range
+
+
+These attributes provide additional scene understanding alongside the retouching prediction.
+
+They can also be useful for debugging, analysis, UI features, or future scene-aware processing logic.
+
+
+---
+
+Why Predict a Recipe Instead of Pixels?
+
+Many neural photo-enhancement systems directly generate a complete output image.
+
+AdaptivePhotoNet takes a different approach.
+
+Pixel-to-pixel model:
+
+Full Image → Neural Network → Full Image
+
+
+AdaptivePhotoNet:
+
+Small Preview → Neural Network → 21 Parameters
+                                    ↓
+Original Full-Resolution Image → Retouching Engine → Output
+
+For photographic retouching, much of the desired transformation can be expressed through global or structured photographic controls.
+
+Predicting these controls instead of millions of output pixels allows the neural network to remain relatively small.
+
+It also keeps the transformation interpretable.
+
+For example, an application can inspect whether the network requested:
+
+Exposure        +0.32 EV
+Temperature     -0.08
+Highlights      -0.21
+Contrast        +0.14
+Saturation      +0.07
+Vignette         0.11
+...
+
+rather than receiving only an opaque generated image.
+
+
+---
+
+Multi-Style Retouching
+
+AdaptivePhotoNet uses a separate style_id input rather than requiring six independent models.
+
+The same photograph can therefore be analyzed under different retouching directions:
+
+┌─ Natural
+                    ├─ Vivid
+Input Photograph ───├─ Cinema
+                    ├─ Portrait
+                    ├─ Film
+                    └─ Moody
+
+The style determines the intended aesthetic direction while the image content determines the actual adjustment recipe.
+
+This means that Film, for example, is not intended to represent one fixed preset applied identically to every photograph.
+
+Two photographs using the same style may receive different exposure, tone, color, curve, and other adjustments according to their visual characteristics.
+
+
+---
+
+Training Dataset
+
+AdaptivePhotoNet was developed together with:
+
+Adaptive Photo Retouching 6-Style Dataset
+
+https://huggingface.co/datasets/Phitran21/adaptive-photo-retouching-6style
+
+The dataset contains original photographs paired with six adaptively retouched variants:
+
+Original
+├── Natural
+├── Vivid
+├── Cinema
+├── Portrait
+├── Film
+└── Moody
+
+The target transformations were generated adaptively for individual images rather than by applying six globally fixed presets.
+
+See the dataset card for details about dataset generation, source data, licensing, and limitations.
+
+
+---
+
+Inference Pipeline
+
+A typical application pipeline is:
+
+1. Load the original image
+             ↓
+2. Create 224 × 224 RGB preview
+             ↓
+3. Normalize to float32 [0, 1]
+             ↓
+4. Convert HWC → NCHW
+             ↓
+5. Select style_id
+             ↓
+6. Run AdaptivePhotoNet
+             ↓
+7. Decode the 21D recipe
+             ↓
+8. Apply recipe to original-resolution image
+             ↓
+9. Produce final retouched photograph
+
+The original full-resolution image does not need to pass through the neural network.
+
+
+---
+
+Minimal ONNX Runtime Example
+
+import numpy as np
+import onnxruntime as ort
+from PIL import Image
+
+STYLE = {
+    "natural": 0,
+    "vivid": 1,
+    "cinema": 2,
+    "portrait": 3,
+    "film": 4,
+    "moody": 5,
+}
+
+image = Image.open("photo.jpg").convert("RGB")
+preview = image.resize((224, 224))
+
+x = np.asarray(preview, dtype=np.float32) / 255.0
+x = np.transpose(x, (2, 0, 1))
+x = np.expand_dims(x, axis=0)
+
+style_id = np.asarray([STYLE["film"]], dtype=np.int64)
+
+session = ort.InferenceSession("AdaptivePhotoNet.onnx")
+
+recipe_vector, scene_probs = session.run(
+    None,
+    {
+        "image": x,
+        "style_id": style_id,
+    },
+)
+
+print("Recipe:", recipe_vector)
+print("Scene probabilities:", scene_probs)
+
+The resulting recipe_vector must then be interpreted according to recipe_schema.json and applied by the corresponding image-retouching pipeline.
+
+
+---
+
+Android / ONNX Runtime
+
+Recommended execution-provider configuration:
+
+FP32
+
+XNNPACKExecutionProvider
+        ↓ fallback
+CPUExecutionProvider
+
+INT8
+
+CPUExecutionProvider
+
+Actual performance depends on device hardware, ONNX Runtime version, thread configuration, quantization method, and preprocessing pipeline.
+
+
+---
+
+Intended Use
+
+AdaptivePhotoNet is intended for experimentation and development in:
+
+automatic photo retouching;
+
+computational photography;
+
+adaptive color grading;
+
+scene-aware image enhancement;
+
+mobile photo editing;
+
+lightweight computer vision;
+
+ONNX Runtime applications;
+
+edge inference;
+
+non-destructive image adjustment prediction.
+
+
+
+---
+
+Limitations
+
+AdaptivePhotoNet predicts photographic adjustments from a 224 × 224 representation of the image.
+
+Fine details that disappear during resizing may therefore not influence the predicted recipe.
+
+The model may also perform less reliably on images significantly outside its training distribution, including unusual lighting, extreme exposure, uncommon photographic styles, or heavily degraded images.
+
+Retouching quality is inherently subjective. Different users may prefer different photographic interpretations of the same image.
+
+The six supported styles represent only six predefined aesthetic directions and should not be interpreted as exhaustive photographic styles.
+
+The model predicts retouching parameters rather than reconstructing or generating image content. It therefore cannot perform tasks such as object removal, image inpainting, semantic image editing, or generative relighting.
+
+
+---
+
+Related Resources
+
+Training Dataset
+
+Adaptive Photo Retouching 6-Style Dataset
+
+https://huggingface.co/datasets/Phitran21/adaptive-photo-retouching-6style
+
+Source Code and Demo
+
+https://github.com/phiiggfdg/adaptive-retouch-6m-onnx
+
+
+---
+
+Author
+
+Trần Phi
+
+Hugging Face:
+https://huggingface.co/Phitran21
+
+GitHub:
+https://github.com/phiiggfdg
+
+Website:
+https://toren.io.vn
+
+
+---