internal_logic.md

Smart Brightness Internal Logic Guide

This document provides a deep dive into the mathematical implementation of Smart Brightness.

Core Architecture

graph TD
    A[Camera Capture] --> B[Dominance Mapping]
    B --> C[Reflection Compensation]
    C --> D[Normalization]
    D --> E[EMA Smoothing]
    E --> F[Day/Night Adjustment]
    F --> G[Brightness Mapping]
    G --> H[Smooth Transition]
    H --> I[Sysfs Write]

Loading

1. Ambient Light Sensing (src/camera.rs)

Smart Brightness uses a Dominance-Coverage model to estimate perceived lighting.

Implementation:

1. Weighted Histogram: Pixels are binned (0-255) and weighted by spatial position (center-priority).
2. 85th Percentile ($L_{85}$): We find the luminance level that 85% of the environment is at or below. This represents the "dominant luminance field."
3. Final Estimation: $$L_{raw} = \frac{0.9 \times L_{85} + 0.1 \times L_{mean}}{255}$$ This ensures that pinpoint light sources (like a desk lamp) don't overpower the global environmental light.

2. Reflection Compensation (src/main.rs)

To prevent screen light reflecting off the user's face from keeping the brightness high in dark rooms:

$$L_{comp} = L_{raw} - (\text{Backlight}_{%} \times \text{anti_reflection})$$

3. Normalization (src/main.rs)

Compensated luma is normalized against the calibrated range:

$$L_{norm} = \text{clamp}\left(\frac{L_{comp} - L_{min}}{L_{max} - L_{min}}, 0.0, 1.0\right)$$

4. Smoothing (src/smoothing.rs)

An Exponential Moving Average (EMA) filters out noise:

$$S_t = \alpha \times L_{norm} + (1 - \alpha) \times S_{t-1}$$ Where $\alpha$ is the smoothing parameter.

5. Day/Night Boost (src/time_adjust.rs)

If day_night_mode is enabled, the light level is scaled by a time-of-day multiplier (e.g., 1.05 during the day).

6. Brightness Mapping (src/main.rs)

Adjusted light levels are mapped to hardware values:

$$B_{target} = \text{round}(L_{adj} \times (B_{max} - B_{min}) + B_{min})$$

7. Transitions (src/smooth_transition.rs)

To avoid jarring snaps, brightness is moved in steps:

$$\text{Step} = \text{clamp}\left(\frac{|B_{target} - B_{current}|}{\text{transition_speed}}, \text{step}_{min}, \text{step}_{max}\right)$$

---

File Structure

File	Responsibility
src/main.rs	Coordination, mapping, and compensation.
src/camera.rs	V4L2 capture and Dominance Histogram.
src/backlight.rs	Sysfs hardware interaction.
src/config.rs	Simplified TOML management.
src/smoothing.rs	EMA noise reduction.
src/smooth_transition.rs	Incremental step logic.
src/time_adjust.rs	Day/Night scheduling.
src/tui.rs	Terminal configuration tool.