add gif via LFS and update README/app

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+screenshots/*.gif filter=lfs diff=lfs merge=lfs -text

README.md

@@ -10,17 +10,23 @@ pinned: false
 
 # Image Quantization and CT Windowing Explorer
 
-An interactive Streamlit app for teaching how quantization and CT-style windowing affect grayscale medical image visualization.
+An interactive Streamlit app for exploring how quantization and CT-style windowing change grayscale medical image display.
+
+## Screenshots / GIF
+
+### Main app overview
+
+![Main app overview](screenshots/demo_overview.gif)
+
 
 ## Project Summary
 
-This app demonstrates two related but different operations:
+This app compares two related but different operations on grayscale medical images:
 
-1. Quantization reduces the number of representable gray levels, which can introduce information loss, banding, and larger reconstruction error.
-2. Windowing is a display operation that maps a selected intensity range to visible grayscale values and clips values outside that range.
+1. Quantization reduces the number of stored gray levels and can introduce banding or reconstruction error.
+2. Windowing changes only how a chosen intensity range is displayed and clips values outside that range.
 
-Users can explore bit depth and window bounds, then observe four synchronized visualization states, histogram behavior, error maps, and summary metrics.
-In the histogram view, the overlaid window bounds act as visual reference markers, while the plotted distributions are intended to highlight quantization effects on stored intensities.
+The interface lets users adjust bit depth and window bounds, then compare four image states, a histogram, an error map, and summary metrics side by side.
 
 ## Local Run
 
@@ -57,30 +63,28 @@ sample_images/builtin_samples/
 docs/
 requirements.txt
 Makefile
+Dockerfile
 ```
 
 ## Features
 
-- Built-in sample images bundled inside the repository
-- Built-in samples derived from CT-RATE, LDCT-and-Projection-data, and RSNA PE sources
-- Upload support for `PNG`, `JPG`, `JPEG`, and `DICOM`
-- Upload support for `NIfTI` volumes (`.nii`, `.nii.gz`)
-- Automatic handling of single-channel grayscale and 3-channel grayscale copies
-- Uniform quantization with adjustable bit depth
-- Adjustable window lower and upper bounds, with CT window presets
-- Slice selection for volumetric inputs and rotation controls for uploaded DICOM/NIfTI files
-- Four-panel visualization: original, windowed, quantized, and quantized + windowed
-- Clickable double-arrow comparison graph that stays synchronized with the metrics selector
-- Intensity histogram with window overlay; the overlay marks the chosen window, while the distribution view focuses on quantization effects
-- Squared-error map for the currently selected comparison
-- Metrics: MSE, PSNR, gray levels used, and entropy
-- In-app explanatory notes for every interactive control
+- Built-in CT-oriented examples from CT-RATE, LDCT-and-Projection-data, and RSNA PE
+- Upload support for `PNG`, `JPG`, `JPEG`, and single-slice `DICOM`
+- Automatic handling of grayscale images, including 3-channel grayscale copies
+- Adjustable quantization bit depth and CT-style window bounds
+- Slice selection for volumetric built-in samples
+- Rotation control for uploaded DICOM slices
+- Four synchronized views: original, windowed, quantized, and quantized + windowed
+- Histogram, squared-error map, and summary metrics (`MSE`, `PSNR`, gray levels, entropy)
+- Clickable comparison arrows synchronized with the metrics selector
+- In-app explanatory notes for each main control
 
 ## Known Limitations
 
 - The app is educational and not intended for clinical interpretation.
 - Uploaded PNG/JPG images may already be restricted to 8-bit precision.
 - The current version works on one 2D slice at a time.
+- Uploaded files are limited to PNG/JPG and single-slice DICOM in the current app; NIfTI upload is not enabled in the active UI.
 - The CT-RATE built-in sample is rotated 90 degrees clockwise in the app to match the expected viewing orientation.
 - Public deployment should still respect the original dataset licenses and redistribution terms for bundled sample content.
 
@@ -88,8 +92,8 @@ Makefile
 
 - **Input source** switches between prepared built-in examples and your own uploaded data.
 - **Built-in sample** lets you compare different CT-oriented datasets quickly.
-- **Slice index** appears for volumetric inputs and chooses the active axial slice.
-- **Rotate uploaded image** appears for uploaded DICOM/NIfTI data when the slice orientation needs correction.
+- **Slice index** appears for volumetric built-in inputs and chooses the active axial slice.
+- **Rotate uploaded image** appears for uploaded DICOM data when the slice orientation needs correction.
 - **Quantization bit depth** controls how many gray levels remain after uniform quantization.
 - The app initializes the quantization display at 4 bits by default, unless the loaded image has a lower maximum bit depth.
 - **CT window preset** applies common lower/upper bound pairs such as lung or mediastinal ranges.
@@ -98,10 +102,6 @@ Makefile
 - **Visualization arrows** can be clicked to choose which pair of panels should be compared.
 - **Metrics → Compare** is synchronized with the arrow graph and updates all downstream plots.
 
-## Screenshots / GIF
-
-Add screenshots here after the UI is finalized.
-
 ## Design Notes
 
 See [docs/design_choices.md](docs/design_choices.md).

app.py

@@ -143,7 +143,7 @@ def maybe_reset_controls(loaded_key: str, default_low: float, default_high: floa
         return
 
     max_bits = int(st.session_state.get("bit_depth_max", 12))
-    bit_depth = min(4, max_bits)
+    bit_depth = min(6, max_bits)
     st.session_state["loaded_key"] = loaded_key
     st.session_state["bit_depth"] = bit_depth
     st.session_state["bit_depth_slider"] = bit_depth

utils.py

@@ -432,7 +432,7 @@ def create_histogram_figure(
         ax.set_ylabel("Count")
         ax.set_title(label, fontsize=10, loc="left")
         ax.legend(loc="upper right", fontsize=8)
-    axes[-1].set_xlabel("Intensity")
+    axes[-1].set_xlabel("Intensity/HU Value")
     fig.suptitle("Intensity Histogram Comparison", fontsize=12)
     fig.tight_layout()
     return fig