🔮 :: Perlin Line Deformation 1

// =============================================================================
// 0. 모듈 및 크레이트 임포트 (Imports)
// =============================================================================
// `nannou::prelude::*`는 nannou 애플리케이션 개발에 필요한 대부분의 기본 타입과 함수를 가져옵니다.
use nannou::prelude::*;

// Perlin 노이즈 생성기를 사용하기 위해 nannou의 noise 모듈에서 Perlin 구조체와 NoiseFn 트레이트를 가져옵니다.
use nannou::noise::{NoiseFn, Perlin};

// =============================================================================
// 1. 메인 함수 (Application Entry Point)
// =============================================================================
// Rust 프로그램의 진입점입니다.
fn main() {
    nannou::app(model)
        .update(update)
        .run();
}

// =============================================================================
// 2. 라인 구조체 정의 (Line Structure)
// =============================================================================
// `Line`은 화면에 그려질 하나의 곡선을 표현합니다.
// 각 라인은 여러 개의 점으로 구성되며, 노이즈 필드에 의해 변형됩니다.
struct Line {
    // 원본 점들의 위치 (변형되지 않은 초기 위치)
    // 이 점들은 변하지 않고, 변형 계산의 기준점으로 사용됩니다.
    original_points: Vec<Point2>,
    
    // 현재 변형된 점들의 위치
    // 노이즈 필드의 영향을 받아 매 프레임마다 다시 계산됩니다.
    deformed_points: Vec<Point2>,
}

impl Line {
    // 라인 생성자: 시작점, 끝점, 그리고 점의 개수를 받아 라인을 초기화합니다.
    // `segments`는 라인을 몇 개의 점으로 나눌지 결정합니다 (많을수록 부드러운 변형).
    fn new(start: Point2, end: Point2, segments: usize) -> Self {
        let mut original_points = Vec::new();
        
        // 시작점에서 끝점까지 균등하게 분할된 점들을 생성합니다.
        // 선형 보간(linear interpolation)을 사용하여 중간 점들을 계산합니다.
        for i in 0..=segments {
            // t는 0.0에서 1.0까지의 보간 비율입니다.
            // i=0일 때 t=0.0 (시작점), i=segments일 때 t=1.0 (끝점)
            let t = i as f32 / segments as f32;
            
            // 선형 보간 공식: point = start + t * (end - start)
            // start * (1-t) + end * t 와 동일한 결과를 제공합니다.
            let x = start.x + t * (end.x - start.x);
            let y = start.y + t * (end.y - start.y);
            
            original_points.push(pt2(x, y));
        }
        
        // 초기에는 변형된 점들도 원본과 동일하게 설정합니다.
        let deformed_points = original_points.clone();
        
        Line {
            original_points,
            deformed_points,
        }
    }
    
    // 노이즈 필드를 기반으로 라인을 변형시킵니다.
    // `perlin`: 노이즈 생성기
    // `time`: 시간 오프셋 (애니메이션을 위해 사용)
    // `strength`: 변형의 강도 (값이 클수록 더 많이 휘어짐)
    fn update(&mut self, perlin: &Perlin, time: f64, strength: f32) {
        // 각 점에 대해 노이즈 기반 변형을 적용합니다.
        for i in 0..self.original_points.len() {
            let original = self.original_points[i];
            
            // 현재 점의 위치에서 노이즈 값을 계산합니다.
            // 3D 노이즈를 사용: (x, y, time)
            // - x, y를 0.003배로 스케일링하여 부드러운 변형을 만듭니다.
            //   (스케일 값이 작을수록 더 큰 패턴, 부드러운 변형)
            // - time을 세 번째 차원으로 사용하여 시간에 따라 노이즈가 변합니다.
            let noise_x = perlin.get([
                original.x as f64 * 0.004,
                original.y as f64 * 0.001,
                time,
            ]);
            
            // y 방향 변형을 위한 독립적인 노이즈를 계산합니다.
            // 10000.0 오프셋을 추가하여 x와 y가 서로 다른 노이즈 패턴을 받도록 합니다.
            // 오프셋이 없으면 x와 y가 동일한 패턴으로 변형되어 대각선 방향으로만 움직입니다.
            let noise_y = perlin.get([
                original.x as f64 * 0.004 + 10000.0, // offset 추가
                original.y as f64 * 0.001 + 10000.0, // offset 추가
                time,
            ]);
            
            // 노이즈 값을 변위(displacement)로 변환합니다.
            // Perlin 노이즈는 -1.0 ~ 1.0 값을 반환하므로, 이를 직접 변위로 사용합니다.
            // `strength`를 곱하여 변형의 정도를 조절합니다.
            let offset_x = noise_x as f32 * strength;
            let offset_y = noise_y as f32 * strength;
            
            // 원본 위치에 변위를 더해 변형된 위치를 계산합니다.
            // 이렇게 하면 라인이 노이즈 필드를 따라 자연스럽게 휘어집니다.
            self.deformed_points[i] = pt2(
                original.x + offset_x,
                original.y + offset_y,
            );
        }
    }
}

// =============================================================================
// 3. 모델 정의 (State Structure)
// =============================================================================
// `Model` 구조체는 애플리케이션의 전체 상태를 저장합니다.
struct Model {
    // Perlin 노이즈 생성기 인스턴스
    perlin: Perlin,
    
    // 화면에 그려질 모든 라인들의 벡터
    lines: Vec<Line>,
    
    // 시간 오프셋: 노이즈 필드를 시간에 따라 변화시키기 위한 변수
    time_offset: f64,
}

// =============================================================================
// 4. 모델 초기화 함수 (Model Initialization)
// =============================================================================
// `model` 함수는 앱 시작 시 한 번만 호출되며, 초기 라인들을 생성합니다.
fn model(app: &App) -> Model {
    // 새로운 창을 생성하고 속성을 설정합니다.
    app.new_window()
        .size(1000, 1000)
        .title("Perlin Noise Flow Field - Line Deformation")
        .view(view)
        .build()
        .unwrap();
    
    // Perlin 노이즈 생성기를 초기화합니다.
    let perlin = Perlin::new();
    
    // 라인 벡터를 생성합니다.
    let mut lines = Vec::new();
    
    // 수평 라인들을 생성합니다.
    // y축 방향으로 -n부터 n까지 n픽셀 간격으로 라인을 배치합니다.
    // `step_by(n)`은 n픽셀마다 하나의 라인을 생성합니다.
    for y in (-500..=500).step_by(20) {
        // 각 수평 라인은 화면의 왼쪽(-n)에서 오른쪽(n)까지 그려집니다.
        // `segments: n`은 각 라인을 n개의 점으로 나눕니다.
        // 점이 많을수록 더 부드럽고 세밀한 변형이 가능합니다.
        lines.push(Line::new(
            pt2(-500.0, y as f32),
            pt2(500.0, y as f32),
            100,  // 각 라인을 n개의 세그먼트로 분할
        ));
    }
    
    // 수직 라인들을 생성합니다.
    // x축 방향으로 -n부터 n까지 n픽셀 간격으로 라인을 배치합니다.
    for x in (-500..=500).step_by(20) {
        // 각 수직 라인은 화면의 아래(-n)에서 위(n)까지 그려집니다.
        lines.push(Line::new(
            pt2(x as f32, -500.0),
            pt2(x as f32, 500.0),
            100,  // 각 라인을 n개의 세그먼트로 분할
        ));
    }
    
    Model {
        perlin,
        lines,
        time_offset: 0.0,
    }
}

// =============================================================================
// 5. 업데이트 함수 (Per-Frame Update Logic)
// =============================================================================
// `update` 함수는 매 프레임마다 호출되어 노이즈 필드를 업데이트하고
// 모든 라인을 변형시킵니다.
fn update(_app: &App, model: &mut Model, _update: Update) {
    // 시간 오프셋을 증가시켜 노이즈 필드를 변화시킵니다.
    // 0.01은 애니메이션 속도를 조절하는 값입니다.
    // - 값이 클수록 빠르게 변화합니다.
    // - 값이 작을수록 천천히, 부드럽게 변화합니다.
    model.time_offset += 0.005;
    
    // 각 라인을 노이즈 필드에 따라 변형시킵니다.
    for line in &mut model.lines {
        // `strength: 100.0`은 변형의 강도입니다.
        // 이 값이 클수록 라인이 더 많이 휘어집니다.
        line.update(&model.perlin, model.time_offset, 100.0);
    }
}

// =============================================================================
// 6. 뷰 함수 (Rendering Logic)
// =============================================================================
// `view` 함수는 매 프레임마다 화면을 그립니다.
fn view(app: &App, model: &Model, frame: Frame) {
    // 드로우 컨텍스트를 생성합니다.
    let draw = app.draw();
    
    // 배경색을 HSLA 모드로 설정합니다.
    draw.background().color(hsla(0.0, 0.0, 0.02, 1.0));
    
    // 모든 라인을 그립니다.
    for line in &model.lines {
        // 라인의 각 세그먼트를 그립니다.
        // 변형된 점들을 순회하면서 연속된 두 점 사이에 선을 그립니다.
        // `.windows(2)`는 벡터의 연속된 두 요소를 슬라이딩 윈도우로 순회합니다.
        // 예: [A, B, C, D] -> [A, B], [B, C], [C, D]
        for window in line.deformed_points.windows(2) {
            // window[0]은 선의 시작점, window[1]은 끝점입니다.
            draw.line()
                .start(window[0])
                .end(window[1])
                .weight(0.5)                        // 선의 두께 1픽셀
                .color(rgba(1.0, 1.0, 1.0, 0.8));   // RGBA 모드: 약간 투명한 흰색
                // R=1.0, G=1.0, B=1.0 (흰색), A=0.8 (80% 불투명)
        }
    }
    
    // 드로우 컨텍스트의 내용을 프레임 버퍼에 렌더링합니다.
    draw.to_frame(app, &frame).unwrap();
}