Update docs with image file loading and Image Viewer demo

Author: nickprotop

README.md

@@ -124,7 +124,7 @@ cd MyApp && dotnet run
 | **Data** | ListControl, TreeControl, TableControl (interactive DataGrid with virtual data, sorting, editing), HorizontalGridControl |
 | **Navigation** | MenuControl, ToolbarControl, TabControl |
 | **Layout** | ColumnContainer, SplitterControl, ScrollablePanelControl, PanelControl |
-| **Drawing** | CanvasControl |
+| **Drawing** | CanvasControl, ImageControl (PNG/JPEG/BMP/GIF/WebP/TIFF via ImageSharp) |
 | **Advanced** | SpectreRenderableControl (wraps any Spectre.Console `IRenderable`), ProgressBarControl, TerminalControl |
 
 ## API Usage

docs/CONTROLS.md

@@ -71,7 +71,7 @@ Controls for custom graphics and free-form drawing.
 | Control | Description | Details |
 |---------|-------------|---------|
 | **[CanvasControl](controls/CanvasControl.md)** | Free-form drawing surface | 30+ drawing primitives, retained & immediate modes, thread-safe async painting |
-| **[ImageControl](IMAGE_RENDERING.md)** | Half-block image renderer | Displays PixelBuffer as 2-pixels-per-cell image with Fit/Fill/Stretch/None scaling |
+| **[ImageControl](IMAGE_RENDERING.md)** | Half-block image renderer | Load PNG/JPEG/BMP/GIF/WebP/TIFF files or PixelBuffer; Fit/Fill/Stretch/None scaling |
 
 ## Layout Controls
 

docs/EXAMPLES.md

@@ -239,6 +239,31 @@ dotnet run --project Examples/CanvasDemo
 
 ---
 
+#### Image Viewer (DemoApp)
+Load and display real image files in the terminal using half-block Unicode rendering.
+
+![Image Viewer](images/examples/imageviewer.png)
+
+```bash
+dotnet run --project Examples/DemoApp
+# Navigate to Rendering → Image Viewer
+```
+
+**Key Features:**
+- Load PNG, JPEG, BMP, GIF, WebP, TIFF files via file picker dialog
+- Half-block rendering (2 vertical pixels per character cell)
+- Four scale modes: Fit, Fill, Stretch, None
+- Resizable window with live image rescaling
+- Keyboard shortcuts: Ctrl+O to open, S to cycle scale, Esc to close
+
+**APIs Demonstrated:**
+- `PixelBuffer.FromFile()` — decode image files via SixLabors.ImageSharp
+- `ImageControl` with `ScaleMode` switching
+- `FileDialogs.ShowFilePickerAsync()` with format filter
+- `HorizontalGridControl` for toolbar layout
+
+---
+
 #### CompositorEffectsExample
 Demonstrates compositor-style buffer manipulation capabilities.
 
@@ -546,6 +571,7 @@ dotnet run --project Examples/PluginShowcaseExample
 | `MultilineEditControl` | DemoApp, TextEditorExample |
 | `LogViewerControl` | DemoApp |
 | `TabControl` | TabControlDemo |
+| `ImageControl` | DemoApp (Image Rendering, Image Viewer) |
 | `CanvasControl` | CanvasDemo |
 | `HorizontalGridControl` | Most examples |
 | `SpectreRenderableControl` | SpectreMouseExample |

docs/IMAGE_RENDERING.md

@@ -6,11 +6,12 @@ SharpConsoleUI can render pixel-based images in the console using Unicode half-b
 
 1. [Overview](#overview)
 2. [PixelBuffer](#pixelbuffer)
-3. [ImageControl](#imagecontrol)
-4. [Scale Modes](#scale-modes)
-5. [Alignment and Scale Mode Interaction](#alignment-and-scale-mode-interaction)
-6. [Half-Block Rendering](#half-block-rendering)
-7. [Creating Test Images](#creating-test-images)
+3. [Loading Images from Files](#loading-images-from-files)
+4. [ImageControl](#imagecontrol)
+5. [Scale Modes](#scale-modes)
+6. [Alignment and Scale Mode Interaction](#alignment-and-scale-mode-interaction)
+7. [Half-Block Rendering](#half-block-rendering)
+8. [Creating Test Images](#creating-test-images)
 
 ## Overview
 
@@ -55,6 +56,50 @@ var argbArray = new int[width * height];
 var buffer = PixelBuffer.FromArgbArray(argbArray, width, height);
 ```
 
+## Loading Images from Files
+
+SharpConsoleUI can load real image files using [SixLabors.ImageSharp](https://github.com/SixLabors/ImageSharp). Supported formats: **PNG, JPEG, BMP, GIF, TIFF, TGA, PBM, WebP**.
+
+### From a File Path
+
+```csharp
+var buffer = PixelBuffer.FromFile("photo.png");
+window.AddControl(Controls.Image(buffer));
+```
+
+### From a Stream
+
+```csharp
+using var stream = File.OpenRead("photo.jpg");
+var buffer = PixelBuffer.FromStream(stream);
+```
+
+### From an ImageSharp Image
+
+If you already have an `Image<Rgb24>` (e.g., after applying ImageSharp processing), convert it directly:
+
+```csharp
+using SixLabors.ImageSharp;
+using SixLabors.ImageSharp.PixelFormats;
+
+using var image = Image.Load<Rgb24>("photo.png");
+image.Mutate(x => x.Resize(200, 100)); // optional pre-processing
+var buffer = PixelBuffer.FromImageSharp(image);
+```
+
+### With File Picker Dialog
+
+```csharp
+var path = await FileDialogs.ShowFilePickerAsync(windowSystem,
+    filter: "*.png;*.jpg;*.jpeg;*.bmp;*.gif;*.webp;*.tiff");
+
+if (path != null)
+{
+    var buffer = PixelBuffer.FromFile(path);
+    imageControl.Source = buffer;
+}
+```
+
 ## ImageControl
 
 Add images to windows using `ImageControl`: