🔮 :: Perlin Noise Flow 3

📝 Rust Code

use nannou::prelude::*;
use nannou::noise::{NoiseFn, Perlin};

fn main() {
    nannou::app(model).update(update).run();
}

struct Particle {
    pos: Vec2, 
    prev_pos: Vec2,
    vel: Vec2,
    acc: Vec2,
}

impl Particle {
    fn new(x: f32, y: f32) -> Self {
        let pos = vec2(x, y);
        Particle {
            pos,
            prev_pos: pos,
            vel: Vec2::ZERO,
            acc: Vec2::ZERO,
        }
    }

    fn update(&mut self) {
        self.vel += self.acc;
        self.vel = self.vel.clamp_length_max(4.0);
        self.prev_pos = self.pos;
        self.pos += self.vel;
        self.acc *= 0.0; 
    }

    fn apply_force(&mut self, force: Vec2) {
        self.acc += force;
    }

    fn edges(&mut self, rect: &Rect) {
        if self.pos.x > rect.right() {
            self.pos.x = rect.left();
            self.prev_pos.x = self.pos.x;
        }
        if self.pos.x < rect.left() {
            self.pos.x = rect.right();
            self.prev_pos.x = self.pos.x;
        }
        if self.pos.y > rect.top() {
            self.pos.y = rect.bottom();
            self.prev_pos.y = self.pos.y;
        }
        if self.pos.y < rect.bottom() {
            self.pos.y = rect.top();
            self.prev_pos.y = self.pos.y;
        }
    }
}

struct Model {
    perlin: Perlin,
    particles: Vec<Particle>,
    time: f64, 
    noise_scale: f64,
}

fn model(app: &App) -> Model {
    let window_id = app.new_window()
        .size(1024, 1024)
        .title("Perlin Noise Flow Field")
        .view(view)
        .build()
        .unwrap();

    let win = app.window(window_id).unwrap().rect();
    let perlin = Perlin::new();
    let time = 0.0;
    let noise_scale = 0.005; 

    let particles = (0..500)
        .map(|_| {
            let x = random_range(win.left(), win.right());
            let y = random_range(win.bottom(), win.top());
            Particle::new(x, y)
        })
        .collect();

    Model {
        perlin,
        particles,
        time,
        noise_scale,
    }
}

fn update(app: &App, model: &mut Model, _update: Update) {
    let win = app.window_rect();

    for p in &mut model.particles {
        let noise_val = model.perlin.get([
            p.pos.x as f64 * model.noise_scale,
            p.pos.y as f64 * model.noise_scale,
            model.time,
        ]);

        let angle = map_range(noise_val, -1.0, 1.0, 0.0, 2.0 * PI as f64) as f32;

        let force = vec2(angle.cos(), angle.sin()) * 0.1;

        p.apply_force(force);
        p.update();
        p.edges(&win);
    }

    model.time += 0.005;
}

fn view(app: &App, model: &Model, frame: Frame) {
    let draw = app.draw();

    if app.elapsed_frames() == 1 {
        draw.background().color(BLACK);
    }
    
    draw.rect()
        .wh(app.window_rect().wh())
        .color(srgba(0.0, 0.0, 0.0, 0.05));

    for p in &model.particles {
        let noise_val_color = model.perlin.get([
            p.pos.x as f64 * model.noise_scale,
            p.pos.y as f64 * model.noise_scale,
            model.time + 100.0, // 색상 변화에 다른 노이즈 시드를 주기 위해 임의의 값을 더함
        ]);

        let hue = map_range(noise_val_color, -1.0, 1.0, 0.5, 1.0);
        let color = hsla(hue as f32, 0.7, 0.6, 0.7);

        draw.line()
            .start(p.prev_pos)
            .end(p.pos)
            .weight(1.5)
            .color(color);
    }

    draw.to_frame(app, &frame).unwrap();
}

📝 Rust Code + Comment

// nannou의 prelude(가장 자주 사용되는 기능들의 모음)를 가져옵니다.
// App, Frame, vec2, aabb, rect, PI, TAU, HSL, 등 핵심 타입과 함수들이 포함되어 있어 편리합니다.
use nannou::prelude::*;
// nannou에 내장된 noise 라이브러리에서 Perlin 노이즈 생성기와,
// 노이즈 값 생성을 위한 `get` 메서드를 제공하는 NoiseFn 트레잇(trait)을 가져옵니다.
use nannou::noise::{NoiseFn, Perlin};


// ======================================================================
// ==== 1. 전역 상수 설정 (Global Constants)
// ======================================================================
// 아트워크의 특성을 결정하는 주요 파라미터들을 상수로 정의합니다.
// 이렇게 하면 코드 상단에서 쉽게 값을 조정하고 실험할 수 있으며, '마법의 숫자'를 피할 수 있습니다.
// `const`는 컴파일 타임에 값이 결정되는 불변 상수입니다.

const NUM_PARTICLES: usize = 500;   // 화면에 생성할 파티클의 총 개수. `usize`는 컬렉션의 인덱싱이나 크기를 나타낼 때 사용되는 부호 없는 정수 타입입니다.
const NOISE_SCALE: f64 = 0.005;   // 노이즈 필드의 스케일. 값이 작을수록 노이즈 패턴이 확대되어(zoom-in) 부드러운 흐름을, 클수록 자글자글한 흐름을 만듭니다.
const MAX_SPEED: f32 = 4.0;       // 각 파티클이 가질 수 있는 최대 속력. 이 값을 통해 파티클이 너무 빠르게 움직이는 것을 방지합니다.
const FORCE_STRENGTH: f32 = 0.1;  // 노이즈 필드가 파티클에 가하는 힘의 세기. 클수록 노이즈 필드의 흐름을 더 강하게 따라갑니다.
const TIME_INCREMENT: f64 = 0.005;  // 매 프레임마다 시간을 얼마나 증가시킬지 결정. 노이즈 필드가 변화하는 속도를 제어합니다.
const TRAIL_ALPHA: f32 = 0.05;    // 잔상 효과를 만들기 위한 배경의 투명도. 0.0에 가까울수록 잔상이 길게 남고, 1.0에 가까우면 거의 남지 않습니다.


// ======================================================================
// ==== 2. 메인 함수 (Main Function)
// ======================================================================
// Rust 프로그램의 진입점(entry point)입니다.
fn main() {
    // nannou 앱을 설정하고 실행합니다. 빌더(builder) 패턴을 사용합니다.
    // app(model): `model` 함수를 사용해 앱의 초기 상태를 설정합니다.
    // .update(update): 매 프레임마다 상태를 변경할 `update` 함수를 지정합니다.
    // .run(): 모든 설정을 마치고 앱의 메인 루프를 시작합니다.
    nannou::app(model).update(update).run();
}


// ======================================================================
// ==== 3. 파티클 구조체 정의 (Particle Struct)
// ======================================================================
// 개별 파티클의 상태를 저장하기 위한 커스텀 데이터 타입(구조체)입니다.
struct Particle {
    pos: Vec2,      // 파티클의 현재 위치 (x, y 좌표). `Vec2`는 nannou의 2차원 벡터 타입입니다.
    prev_pos: Vec2, // 파티클의 이전 프레임 위치. 현재 위치와 연결하여 궤적(선)을 그리는 데 사용됩니다.
    vel: Vec2,      // 파티클의 속도 (x, y 방향의 속도). 매 프레임 위치에 더해져 움직임을 만듭니다.
}


// ======================================================================
// ==== 4. 파티클 메서드 구현 (Particle Implementation)
// ======================================================================
// `impl` 키워드는 특정 구조체(여기서는 Particle)에 대한 메서드(함수)를 구현하는 블록입니다.
impl Particle {
    // `Particle`의 생성자(constructor) 역할을 하는 연관 함수(associated function)입니다.
    // `&self`를 인자로 받지 않으므로 `Particle::new(...)` 형태로 호출합니다.
    fn new(x: f32, y: f32) -> Self {
        let pos = vec2(x, y); // `vec2` 함수로 `Vec2` 타입의 위치 벡터를 생성합니다.
        
        // 새로운 Particle 인스턴스를 생성하여 반환합니다.
        Particle {
            pos,                  // 현재 위치를 초기화합니다.
            prev_pos: pos,        // 처음에는 이전 위치와 현재 위치가 같습니다.
            vel: Vec2::ZERO,      // 처음 속도는 0입니다. `Vec2::ZERO`는 `vec2(0.0, 0.0)`와 같습니다.
        }
    }

    // 외부에서 주어진 힘(force)을 기반으로 파티클의 속도와 위치를 업데이트합니다.
    // `&mut self`는 이 메서드가 Particle 인스턴스의 데이터를 '수정(mutate)'할 수 있음을 의미합니다.
    fn update_with_force(&mut self, force: Vec2) {
        // 힘을 가속도로 간주하여 속도에 더합니다. (질량=1로 가정)
        let acc = force; 
        
        // 속도 업데이트 및 최대 속력 제한
        self.vel += acc;
        // `clamp_length_max`는 벡터의 방향은 유지한 채, 크기(길이)가 최댓값을 넘지 않도록 제한하는 편리한 메서드입니다.
        self.vel = self.vel.clamp_length_max(MAX_SPEED);
        
        // 위치 업데이트
        self.prev_pos = self.pos;  // 현재 위치를 이전 위치로 기록합니다.
        self.pos += self.vel;      // 속도를 현재 위치에 더하여 다음 위치를 계산합니다.
    }

    // 파티클이 화면 경계를 벗어났을 때, 반대편에서 다시 나타나도록 처리합니다 (화면 감싸기).
    fn edges(&mut self, rect: &Rect) {
        // `rect`는 화면의 사각형 영역 정보를 담고 있습니다.
        if self.pos.x > rect.right()  { self.pos.x = rect.left();  self.prev_pos.x = self.pos.x; }
        if self.pos.x < rect.left()   { self.pos.x = rect.right(); self.prev_pos.x = self.pos.x; }
        if self.pos.y > rect.top()    { self.pos.y = rect.bottom();self.prev_pos.y = self.pos.y; }
        if self.pos.y < rect.bottom() { self.pos.y = rect.top();   self.prev_pos.y = self.pos.y; }
        // 경계를 넘을 때 `prev_pos`도 함께 수정해주는 것이 중요합니다.
        // 그렇지 않으면 화면을 가로지르는 긴 선이 그려지게 됩니다.
    }
}


// ======================================================================
// ==== 5. 모델(상태) 구조체 정의 (Model Struct)
// ======================================================================
// nannou 앱의 전체 상태(state)를 담는 구조체입니다.
// 이 `Model`의 인스턴스가 `update`와 `view` 함수 사이에서 계속 전달되며 앱의 생명주기를 관리합니다.
struct Model {
    perlin: Perlin,                 // Perlin 노이즈 생성기 인스턴스.
    particles: Vec<Particle>,       // 모든 `Particle`들을 담고 있는 동적 배열(Vector).
    time: f64,                      // 애니메이션을 위한 시간 값. 3D 노이즈의 z축으로 사용됩니다.
}


// ======================================================================
// ==== 6. 모델 초기화 함수 (Model Initialization)
// ======================================================================
// 앱이 시작될 때 단 한 번 호출되어 `Model`의 초기 상태를 설정합니다.
fn model(app: &App) -> Model {
    // 창(window)을 생성하고, 크기/제목 등을 설정한 뒤, `view` 함수를 이 창의 렌더링 루프로 지정합니다.
    app.new_window()
        .size(1024, 1024)
        .title("Perlin Noise Flow Field (Refactored & Commented)")
        .view(view) // 이 창을 그릴 때 `view` 함수를 사용하라고 알려줍니다.
        .build()
        .unwrap(); // `build()`는 `Result`를 반환하므로, `unwrap()`으로 성공적인 결과를 추출합니다.

    let win = app.window_rect(); // 현재 창의 사각형 영역 정보를 가져옵니다.
    let perlin = Perlin::new();  // 새로운 Perlin 노이즈 생성기를 만듭니다.

    // Rust의 이터레이터(iterator)와 `map`, `collect`를 사용하여 파티클을 효율적으로 생성합니다.
    let particles = (0..NUM_PARTICLES) // 0부터 `NUM_PARTICLES - 1`까지의 숫자 범위를 만듭니다.
        .map(|_| { // 각 숫자에 대해 다음 클로저(closure, 익명 함수)를 실행합니다. `_`는 숫자를 사용하지 않겠다는 의미입니다.
            // 화면 내 무작위 위치를 지정합니다.
            let x = random_range(win.left(), win.right());
            let y = random_range(win.bottom(), win.top());
            Particle::new(x, y) // 해당 위치에 새로운 파티클을 생성합니다.
        })
        .collect(); // `map`을 통해 생성된 모든 `Particle`들을 모아 `Vec<Particle>` 컬렉션을 만듭니다.

    // 완성된 초기 상태를 담은 `Model` 인스턴스를 반환합니다.
    Model {
        perlin,
        particles,
        time: 0.0, // 시간은 0에서 시작합니다.
    }
}


// ======================================================================
// ==== 7. 상태 업데이트 함수 (State Update Function)
// ======================================================================
// 매 프레임마다 `view` 함수가 호출되기 직전에 실행됩니다.
// 앱의 논리적인 상태(위치, 속도 등)를 계산하고 변경하는 역할을 합니다.
fn update(app: &App, model: &mut Model, _update: Update) {
    let win = app.window_rect();

    // `&mut model.particles`를 통해 각 파티클을 가변적으로 빌려와 상태를 수정할 수 있습니다.
    for p in &mut model.particles {
        // 파티클의 현재 위치(x, y)와 현재 시간(time)을 이용해 3D Perlin 노이즈 값을 얻습니다.
        let noise_val = model.perlin.get([
            p.pos.x as f64 * NOISE_SCALE, // x, y 좌표에 스케일을 곱해 노이즈 상세도를 조절합니다.
            p.pos.y as f64 * NOISE_SCALE, // `get`은 f64 배열을 받으므로 타입 캐스팅(as f64)이 필요합니다.
            model.time,                   // z축 값으로 시간을 넣어 노이즈 필드가 시간에 따라 변하게 합니다.
        ]);

        // 노이즈 값(-1.0 ~ 1.0)을 각도(0 ~ 2π) 범위로 변환합니다.
        // `TAU`는 nannou prelude에 정의된 상수이며 `2.0 * PI`와 같습니다. 원 전체를 다룰 때 가독성이 좋습니다.
        let angle = map_range(noise_val, -1.0, 1.0, 0.0, TAU as f64) as f32;
        
        // 계산된 각도를 바탕으로 힘(force) 벡터를 생성합니다.
        // `(angle.cos(), angle.sin())`은 해당 각도의 방향을 나타내는 단위 벡터(길이가 1인 벡터)를 만듭니다.
        let force = vec2(angle.cos(), angle.sin()) * FORCE_STRENGTH;

        // 계산된 힘으로 파티클의 상태를 업데이트하고, 화면 경계를 처리합니다.
        p.update_with_force(force);
        p.edges(&win);
    }

    // 다음 프레임을 위해 시간을 약간 증가시킵니다.
    model.time += TIME_INCREMENT;
}


// ======================================================================
// ==== 8. 드로잉 함수 (View / Drawing Function)
// ======================================================================
// 매 프레임마다 `update` 함수가 실행된 후에 호출됩니다.
// 현재 `Model`의 상태를 바탕으로 화면에 그림을 그리는 역할을 합니다.
fn view(app: &App, model: &Model, frame: Frame) {
    let draw = app.draw(); // `Draw` 인스턴스를 가져옵니다. 모든 그리기 명령은 이 `draw` 객체를 통해 이루어집니다.

    // 첫 프레임에만 배경을 완전히 검은색으로 칠합니다.
    if app.elapsed_frames() == 1 {
        draw.background().color(BLACK);
    }
    
    // 매 프레임, 이전에 그려진 그림 위에 반투명한 검은 사각형을 덮어 그립니다.
    // 이 과정이 반복되면서 파티클의 움직임에 자연스러운 잔상(trail) 효과가 생깁니다.
    draw.rect()
        .wh(app.window_rect().wh()) // 창 전체 크기의 사각형
        .color(srgba(0.0, 0.0, 0.0, TRAIL_ALPHA)); // `srgba`는 투명도를 포함한 색상입니다.

    // 모든 파티클을 순회하며 화면에 그립니다. 이번에는 상태를 수정하지 않으므로 `&model.particles`로 빌려옵니다.
    for p in &model.particles {
        // 색상을 결정하기 위해 다른 노이즈 값을 가져옵니다.
        // `time + 100.0` 처럼 시간에 큰 값을 더해주면, 움직임의 방향과 색상 변화가
        // 서로 다른 패턴을 가지게 되어 더 흥미로운 시각적 효과를 만듭니다.
        let noise_val_color = model.perlin.get([
            p.pos.x as f64 * NOISE_SCALE,
            p.pos.y as f64 * NOISE_SCALE,
            model.time + 100.0,
        ]);

        // 노이즈 값을 HSL 색상 모델의 색상(Hue) 값으로 변환합니다.
        // HSL 모델에서 Hue 값을 연속적으로 바꾸면 무지개처럼 부드러운 색상 전환을 얻을 수 있습니다.
        let hue = map_range(noise_val_color, -1.0, 1.0, 0.5, 1.0); // 파란색~보라색~빨간색 계열
        let color = hsla(hue as f32, 0.7, 0.6, 0.7); // Hue, Saturation, Lightness, Alpha

        // 파티클의 이전 위치에서 현재 위치까지 선을 그어 궤적을 표현합니다.
        draw.line()
            .start(p.prev_pos)
            .end(p.pos)
            .weight(1.5) // 선의 두께
            .color(color);
    }

    // 지금까지 버퍼에 쌓인 모든 그리기 명령들을 실제 프레임에 렌더링합니다.
    draw.to_frame(app, &frame).unwrap();
}