Skip to content

AI media harness for planning, generating, and editing locally

TypeScript
10.8 KB
Raw Blame
//! Portable authoring settings; calibration files belong to the generation host.
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
mod calibration;
pub use calibration::DriftCalibration;

#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct GenerationEffects {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub color: Option<Color>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tone: Option<Tone>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub sharpness: Option<Strength>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub anchor: Option<Anchor>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub drift: Option<Drift>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub start_step: Option<i32>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub end_step: Option<i32>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub region: Option<Region>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Color {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub enabled: Option<bool>, pub color: String, pub strength: f32, pub mode: String,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Tone {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub enabled: Option<bool>, pub contrast: f32, pub brightness: f32, pub saturation: f32, pub temperature: f32,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Strength { #[serde(default, skip_serializing_if = "Option::is_none")] pub enabled: Option<bool>, pub strength: f32 }
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Anchor { #[serde(default, skip_serializing_if = "Option::is_none")] pub enabled: Option<bool>, pub mode: String, pub strength: f32 }
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct Drift {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub enabled: Option<bool>,
    pub strength: f32, pub max: f32, pub highlight_strength: f32, pub highlight_knee: f32,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub calibration: Option<DriftCalibration>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Region { pub x: f32, pub y: f32, pub width: f32, pub height: f32, pub invert: bool }

fn range(value: f32, min: f32, max: f32) -> bool { value.is_finite() && (min..=max).contains(&value) }
impl GenerationEffects {
    pub fn validate(&self) -> Result<(), String> {
        let invalid = self.color.as_ref().is_some_and(|c| !range(c.strength, 0.0, 2.0)
            || c.color.len() != 7 || !c.color.starts_with('#') || !c.color.as_bytes()[1..].iter().all(u8::is_ascii_hexdigit)
            || !matches!(c.mode.as_str(), "interpolated" | "type_i" | "type_ii"))
            || self.tone.as_ref().is_some_and(|t| !range(t.contrast, 0.0, 4.0) || !range(t.brightness, -1.0, 1.0) || !range(t.saturation, 0.0, 4.0) || !range(t.temperature, -1.0, 1.0))
            || self.sharpness.as_ref().is_some_and(|s| !range(s.strength, -5.0, 5.0))
            || self.anchor.as_ref().is_some_and(|a| !range(a.strength, 0.0, 1.0) || !matches!(a.mode.as_str(), "self" | "smooth"))
            || self.drift.as_ref().is_some_and(|d| !range(d.strength, 0.0, 1.0) || !range(d.max, 0.0, 10.0) || !range(d.highlight_strength, 0.0, 1.0) || !range(d.highlight_knee, 0.0, 2.0)
                || d.strength > 0.0 && d.max > 0.0 && d.calibration.is_none())
            || self.start_step.unwrap_or(0) < 0 || self.end_step.unwrap_or(i32::MAX) < self.start_step.unwrap_or(0)
            || self.region.as_ref().is_some_and(|r| !range(r.x, 0.0, 100.0) || !range(r.y, 0.0, 100.0) || !range(r.width, 0.1, 100.0) || !range(r.height, 0.1, 100.0) || r.x + r.width > 100.0 || r.y + r.height > 100.0);
        if invalid { return Err("Invalid generation effects settings.".into()); }
        if let Some(calibration) = self.drift.as_ref().and_then(|d| d.calibration.as_ref()) { calibration.bytes()?; }
        Ok(())
    }

    /// Translate to the native LCS schema; bypassed/neutral cards do no work.
    pub fn native_settings(&self) -> Result<Option<Value>, String> {
        self.validate()?;
        let mut settings = json!({});
        if let Some(c) = self.color.as_ref().filter(|c| c.enabled != Some(false) && c.strength != 0.0) {
            let rgb: Vec<f32> = [1, 3, 5].into_iter().map(|i| u8::from_str_radix(&c.color[i..i + 2], 16).unwrap() as f32 / 255.0).collect();
            settings["color"] = json!(rgb); settings["strength"] = json!(c.strength); settings["mode"] = json!(c.mode);
        }
        if let Some(t) = self.tone.as_ref().filter(|t| t.enabled != Some(false) && (t.contrast != 1.0 || t.brightness != 0.0 || t.saturation != 1.0 || t.temperature != 0.0)) {
            settings["contrast"] = json!(t.contrast); settings["brightness"] = json!(t.brightness);
            settings["saturation"] = json!(t.saturation); settings["temperature"] = json!(t.temperature);
        }
        if let Some(s) = self.sharpness.as_ref().filter(|s| s.enabled != Some(false) && s.strength != 0.0) { settings["sharpness"] = json!(s.strength); }
        if let Some(a) = self.anchor.as_ref().filter(|a| a.enabled != Some(false) && a.strength != 0.0) { settings["anchor"] = json!(a.mode); settings["anchor_strength"] = json!(a.strength); }
        if let Some(d) = self.drift.as_ref().filter(|d| d.enabled != Some(false)) {
            if d.strength > 0.0 && d.max > 0.0 { settings["drift_strength"] = json!(d.strength); settings["drift_max"] = json!(d.max); }
            if d.highlight_strength > 0.0 { settings["highlight_strength"] = json!(d.highlight_strength); settings["highlight_knee"] = json!(d.highlight_knee); }
        }
        if settings.as_object().unwrap().is_empty() { return Ok(None); }
        settings["start_step"] = json!(self.start_step.unwrap_or(0));
        settings["end_step"] = json!(self.end_step.unwrap_or(i32::MAX));
        Ok(Some(settings))
    }

    pub fn mask(&self, width: i32, height: i32) -> Result<Option<Vec<f32>>, String> {
        self.validate()?;
        let Some(r) = &self.region else { return Ok(None); };
        if width <= 0 || height <= 0 || i64::from(width) * i64::from(height) > 4_194_304 { return Err("Invalid LCS mask dimensions.".into()); }
        // Fractional coverage keeps small regions useful at latent resolution.
        let overlap = |index: i32, count: i32, start: f32, size: f32| {
            let left = start / 100.0 * count as f32;
            let right = (start + size) / 100.0 * count as f32;
            (right.min((index + 1) as f32) - left.max(index as f32)).clamp(0.0, 1.0)
        };
        Ok(Some((0..height).flat_map(|y| (0..width).map(move |x| {
            let coverage = overlap(x, width, r.x, r.width) * overlap(y, height, r.y, r.height);
            if r.invert { 1.0 - coverage } else { coverage }
        })).collect()))
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn shared_fixture_roundtrips_and_maps_to_native_controls() {
        let fixture: Value = serde_json::from_str(include_str!("../../../fixtures/generation-effects.json")).unwrap();
        let effects: GenerationEffects = serde_json::from_value(fixture.clone()).unwrap();
        effects.validate().unwrap();
        let native = effects.native_settings().unwrap().unwrap();
        assert_eq!(native["start_step"], 2);
        assert_eq!(native["anchor"], "self");
        assert_eq!(native["contrast"], 1.25);
        assert_eq!(native["drift_strength"], 0.5);
        assert_eq!(native["drift_max"], 1.0);
        assert_eq!(native["highlight_strength"], 0.5);
        assert!((native["highlight_knee"].as_f64().unwrap() - 0.8).abs() < 0.00001);
        assert!(native.get("sharpness").is_none());
        assert!((native["color"][0].as_f64().unwrap() - 128.0 / 255.0).abs() < 0.00001);
        let roundtrip: GenerationEffects = serde_json::from_value(serde_json::to_value(&effects).unwrap()).unwrap();
        assert_eq!(effects, roundtrip);
        assert_eq!(effects.mask(4, 2).unwrap().unwrap(), vec![0., 1., 1., 0., 0., 1., 1., 0.]);
        let mut inverted = effects.clone(); inverted.region.as_mut().unwrap().invert = true;
        assert_eq!(inverted.mask(4, 1).unwrap().unwrap(), vec![1., 0., 0., 1.]);
        assert_eq!(effects.mask(2, 1).unwrap().unwrap(), vec![0.5, 0.5]);
    }
    #[test]
    fn rejects_invalid_values_even_when_bypassed_and_skips_neutral_settings() {
        for value in [json!({"color":{"color":"#xyzxyz","strength":0.5,"mode":"type_i"}}),
            json!({"sharpness":{"strength":6,"enabled":false}}), json!({"startStep":4,"endStep":3}),
            json!({"region":{"x":60,"y":0,"width":50,"height":100,"invert":false}})] {
            assert!(serde_json::from_value::<GenerationEffects>(value).unwrap().validate().is_err());
        }
        let neutral: GenerationEffects = serde_json::from_value(json!({"tone":{"contrast":1,"brightness":0,"saturation":1,"temperature":0},"sharpness":{"strength":1,"enabled":false}})).unwrap();
        assert!(neutral.native_settings().unwrap().is_none());
        assert!(serde_json::from_value::<GenerationEffects>(json!({"sharpness":{"strength":true}})).is_err());
    }
    #[test]
    fn drift_controls_are_independent_bounded_and_bypassable() {
        let mut effects: GenerationEffects = serde_json::from_value(json!({"drift":{"strength":0,"max":1,"highlightStrength":0.5,"highlightKnee":0.8}})).unwrap();
        let native = effects.native_settings().unwrap().unwrap();
        assert_eq!(native["highlight_strength"], 0.5);
        assert!(native.get("drift_strength").is_none());
        effects.drift.as_mut().unwrap().enabled = Some(false);
        assert!(effects.native_settings().unwrap().is_none());
        effects.drift.as_mut().unwrap().enabled = None;
        effects.drift.as_mut().unwrap().highlight_strength = 0.;
        assert!(effects.native_settings().unwrap().is_none());
        effects.drift.as_mut().unwrap().strength = 0.5;
        assert!(effects.validate().is_err()); // learned correction requires fitted data
        let fixture: GenerationEffects = serde_json::from_str(include_str!("../../../fixtures/generation-effects.json")).unwrap();
        for (field, value) in [("strength", 1.1), ("max", -1.), ("max", 11.), ("highlightStrength", 1.1), ("highlightKnee", 2.1)] {
            let mut invalid = serde_json::to_value(&fixture).unwrap();
            invalid["drift"]["enabled"] = json!(false);
            invalid["drift"][field] = json!(value);
            assert!(serde_json::from_value::<GenerationEffects>(invalid).unwrap().validate().is_err());
        }
    }
}