🔮 :: Perlin Noise Flow 2

📝 Rust Code

// =============================================================================
// 0. 모듈 및 크레이트 임포트 (Imports)
// =============================================================================
// `nannou::prelude::*`는 nannou 애플리케이션 개발에 필요한 대부분의 기본 타입과 함수를 가져옵니다.
// 벡터(Point2, Vec2), 색상(rgba), 유틸리티 함수(map_range 등)가 포함됩니다.
use nannou::prelude::*;

// Perlin 노이즈 생성기를 사용하기 위해 nannou의 noise 모듈에서 Perlin 구조체와 NoiseFn 트레이트를 가져옵니다.
// Perlin은 자연스러운 연속적인 노이즈 패턴을 생성하는 데 사용됩니다.
use nannou::noise::{NoiseFn, Perlin};

// =============================================================================
// 1. 메인 함수 (Application Entry Point)
// =============================================================================
// Rust 프로그램의 진입점입니다.
// nannou 앱을 초기화하고 이벤트 루프를 실행합니다.
fn main() {
    nannou::app(model)
        .update(update)  // 매 프레임마다 호출될 업데이트 함수 지정
        .run();          // 앱 실행 및 이벤트 루프 시작
}

// =============================================================================
// 2. 파티클 구조체 정의 (Particle Structure)
// =============================================================================
// `Particle`은 flow field를 따라 움직이는 개별 입자를 표현합니다.
struct Particle {
    // 파티클의 현재 위치 (2D 좌표)
    position: Point2,
    
    // 파티클의 이전 위치 (궤적을 그리기 위해 필요)
    prev_position: Point2,
    
    // 파티클의 현재 속도 벡터
    velocity: Vec2,
    
    // 파티클이 화면 밖으로 나갔는지 여부를 추적
    // true일 경우 새 위치에서 재시작됩니다.
    is_out_of_bounds: bool,
}

impl Particle {
    // 파티클 생성자: 무작위 위치에 파티클을 초기화합니다.
    // `bounds`는 화면의 경계를 나타내는 Rect 구조체입니다.
    fn new(bounds: Rect) -> Self {
        // 화면의 무작위 위치를 생성합니다.
        // `random_range(min, max)`는 min과 max 사이의 무작위 값을 반환합니다.
        let x = random_range(bounds.left(), bounds.right());
        let y = random_range(bounds.bottom(), bounds.top());
        let position = pt2(x, y);
        
        Particle {
            position,
            prev_position: position,  // 초기에는 이전 위치와 현재 위치가 동일
            velocity: vec2(0.0, 0.0), // 초기 속도는 0
            is_out_of_bounds: false,
        }
    }
    
    // flow field에서 힘을 받아 파티클을 업데이트합니다.
    // `force`는 노이즈 기반으로 계산된 방향 벡터입니다.
    fn update(&mut self, force: Vec2, bounds: Rect) {
        // 이전 위치를 현재 위치로 업데이트 (궤적 그리기용)
        self.prev_position = self.position;
        
        // 가속도 = 힘 (뉴턴의 제2법칙 F=ma에서 질량을 1로 가정)
        let acceleration = force;
        
        // 속도에 가속도를 더합니다 (속도 업데이트)
        self.velocity += acceleration;
        
        // 속도에 제한을 둡니다 (너무 빠르게 움직이는 것을 방지)
        // 벡터의 크기를 계산하고, 최대값보다 크면 정규화 후 최대값을 곱합니다.
        let max_speed = 2.0;
        let speed = self.velocity.length();
        if speed > max_speed {
            self.velocity = self.velocity.normalize() * max_speed;
        }
        
        // 위치를 속도만큼 이동시킵니다
        self.position += self.velocity;
        
        // 경계 검사: 파티클이 화면 밖으로 나갔는지 확인
        if self.position.x < bounds.left() 
            || self.position.x > bounds.right()
            || self.position.y < bounds.bottom() 
            || self.position.y > bounds.top() 
        {
            self.is_out_of_bounds = true;
        }
    }
    
    // 파티클을 새로운 무작위 위치에서 재시작합니다.
    fn reset(&mut self, bounds: Rect) {
        let x = random_range(bounds.left(), bounds.right());
        let y = random_range(bounds.bottom(), bounds.top());
        self.position = pt2(x, y);
        self.prev_position = self.position;
        self.velocity = vec2(0.0, 0.0);
        self.is_out_of_bounds = false;
    }
}

// =============================================================================
// 3. 모델 정의 (State Structure)
// =============================================================================
// `Model` 구조체는 애플리케이션의 전체 상태를 저장합니다.
struct Model {
    // Perlin 노이즈 생성기 인스턴스
    perlin: Perlin,
    
    // 화면에 그릴 모든 파티클들의 벡터
    // 파티클 개수가 많을수록 더 조밀한 라인이 그려집니다.
    particles: Vec<Particle>,
    
    // 시간 오프셋: 노이즈 필드를 시간에 따라 변화시키기 위한 변수
    // 이 값이 증가하면 노이즈 패턴이 애니메이션됩니다.
    time_offset: f64,
}

// =============================================================================
// 4. 모델 초기화 함수 (Model Initialization)
// =============================================================================
// `model` 함수는 앱 시작 시 한 번만 호출되며, 초기 상태를 설정합니다.
fn model(app: &App) -> Model {
    // 새로운 창을 생성하고 속성을 설정합니다.
    app.new_window()
        .size(800, 800)                      // 창 크기: 800x800 픽셀
        .title("Perlin Noise Flow Field")    // 창 제목
        .view(view)                          // 렌더링 함수 지정
        .build()                             // 창 빌드
        .unwrap();                           // 오류 발생 시 패닉
    
    // Perlin 노이즈 생성기를 초기화합니다.
    let perlin = Perlin::new();
    
    // 파티클 벡터를 생성합니다.
    let mut particles = Vec::new();
    
    // 화면의 경계를 가져옵니다.
    // `app.window_rect()`는 현재 창의 경계 정보를 반환합니다.
    let bounds = app.window_rect();
    
    // 2000개의 파티클을 생성합니다.
    // 이 숫자를 조절하면 라인의 밀도를 변경할 수 있습니다.
    for _ in 0..2000 {
        particles.push(Particle::new(bounds));
    }
    
    // 초기화된 Model을 반환합니다.
    Model {
        perlin,
        particles,
        time_offset: 0.0,  // 시간 오프셋은 0에서 시작
    }
}

// =============================================================================
// 5. 업데이트 함수 (Per-Frame Update Logic)
// =============================================================================
// `update` 함수는 매 프레임마다 호출되어 애니메이션을 진행시킵니다.
fn update(app: &App, model: &mut Model, _update: Update) {
    // 화면 경계를 가져옵니다.
    let bounds = app.window_rect();
    
    // 시간 오프셋을 증가시켜 노이즈 필드를 변화시킵니다.
    // 0.005는 변화 속도를 조절하는 값입니다 (값이 클수록 빠르게 변함).
    model.time_offset += 0.005;
    
    // 각 파티클을 업데이트합니다.
    for particle in &mut model.particles {
        // 파티클이 화면 밖으로 나갔다면 재시작합니다.
        if particle.is_out_of_bounds {
            particle.reset(bounds);
        }
        
        // 현재 파티클 위치에 대한 노이즈 값을 계산합니다.
        // 3D 노이즈를 사용하며, 세 번째 차원은 시간(time_offset)입니다.
        // - x, y 좌표를 0.005배로 스케일링하여 노이즈의 "주파수"를 조절합니다.
        //   (값이 작을수록 더 부드럽고 큰 패턴이 생성됨)
        // - time_offset을 추가하여 시간에 따라 노이즈 패턴이 변화합니다.
        let noise_val = model.perlin.get([
            particle.position.x as f64 * 0.005,
            particle.position.y as f64 * 0.005,
            model.time_offset,
        ]);
        
        // 노이즈 값을 각도로 변환합니다.
        // Perlin 노이즈는 -1.0 ~ 1.0 값을 반환하므로, 이를 0 ~ 2π (360도) 범위로 매핑합니다.
        // 이 각도가 파티클이 이동할 방향을 결정합니다.
        let angle = map_range(noise_val, -1.0, 1.0, 0.0, std::f64::consts::TAU);
        
        // 각도를 이용해 단위 벡터를 생성합니다.
        // 삼각함수를 사용하여 각도를 x, y 좌표로 변환합니다.
        // cos(angle)은 x 방향, sin(angle)은 y 방향 성분을 제공합니다.
        // 0.1을 곱하여 힘의 크기를 조절합니다 (값이 클수록 빠르게 움직임).
        let force = vec2((angle as f32).cos(), (angle as f32).sin()) * 0.1;
        
        // 파티클에 힘을 적용하여 업데이트합니다.
        particle.update(force, bounds);
    }
}

// =============================================================================
// 6. 뷰 함수 (Rendering Logic)
// =============================================================================
// `view` 함수는 매 프레임마다 화면을 그립니다.
fn view(app: &App, model: &Model, frame: Frame) {
    // 드로우 컨텍스트를 생성합니다.
    let draw = app.draw();
    
    // 배경을 반투명한 검은색으로 설정합니다.
    // RGBA 모드를 사용하며, 알파값(0.05)을 낮게 설정하여 페이드 효과를 만듭니다.
    // 이렇게 하면 이전 프레임의 라인이 서서히 사라지면서 궤적 효과가 생깁니다.
    // 알파값이 낮을수록 궤적이 더 길게 남습니다.
    draw.rect()
        .x_y(0.0, 0.0)
        .w_h(800.0, 800.0)
        .color(rgba(0.0, 0.0, 0.0, 0.05));
    
    // 각 파티클의 궤적을 그립니다.
    for particle in &model.particles {
        // 파티클의 현재 위치와 이전 위치 사이에 선을 그립니다.
        // 이렇게 하면 파티클이 이동한 경로가 라인으로 표시됩니다.
        draw.line()
            .start(particle.prev_position)  // 선의 시작점
            .end(particle.position)         // 선의 끝점
            .weight(1.0)                    // 선의 두께 (픽셀)
            .color(rgba(1.0, 1.0, 1.0, 0.5)); // RGBA 모드: 반투명한 흰색
            // R=1.0 (빨강 최대), G=1.0 (초록 최대), B=1.0 (파랑 최대) = 흰색
            // A=0.5 (반투명)
    }
    
    // 드로우 컨텍스트의 내용을 프레임 버퍼에 렌더링합니다.
    draw.to_frame(app, &frame).unwrap();
}