vecs-ts

A modern, intuitive, and high-performance vector and matrix library for TypeScript and JavaScript.

vecs-ts는 2D, 3D, 4D 벡터 및 행렬 연산을 위한 포괄적인 기능을 제공하며, 게임 개발, 컴퓨터 그래픽스, 물리 시뮬레이션 등 수학적 계산이 필요한 모든 프로젝트에 적합하도록 설계되었습니다. TypeScript로 작성되어 타입 안정성을 보장하며, 컴파일된 JavaScript는 모든 최신 환경에서 사용할 수 있습니다.

✨ 특징 (Features)

• 직관적인 API: add, mul, dot, cross 등 명확하고 이해하기 쉬운 메서드 이름을 사용합니다.
• 타입 안전성: TypeScript로 작성되어 개발 단계에서 오류를 줄이고 자동 완성을 완벽하게 지원합니다.
• 성능 최적화: 내부적으로 Float64Array 및 Int32Array를 사용하여 메모리 효율성과 계산 속도를 높였습니다.
• 불변성 및 가변성 지원: .clone 게터(getter)나 정적 메서드(Vec3.add())를 사용하여 불변성을 유지하거나, 인스턴스 메서드(vec.add())를 통해 가변적으로(in-place) 연산하여 성능을 최적화할 수 있습니다.
• 포괄적인 기능: Vec2, Vec3, Vec4, Quat, Mat2, Mat3 등 필수적인 모든 타입을 지원하며, 선형 보간(lerp), 구면 선형 보간(slerp), 정규화, 반사, 회전 등 풍부한 유틸리티를 제공합니다.
• 이터러블(Iterable): 모든 벡터와 행렬 클래스는 이터러블 프로토콜을 구현하여 for...of 루프나 스프레드 문법(...)과 함께 자연스럽게 사용할 수 있습니다.

🚀 설치 (Installation)

npm install vecs-ts

💡 사용법 (Usage)

기본 가져오기 (Import)

import { Vec2, Vec3, Quat, Mat3 } from 'vecs-ts';

Vec3 사용 예시

// 벡터 생성
const v1 = new Vec3(1, 2, 3);
const v2 = new Vec3(4, 5, 6);

// --- 불변 연산 (정적 메서드 사용) ---
// 새로운 Vec3 객체를 반환하며, 원본(v1, v2)은 변경되지 않습니다.
const v3 = Vec3.add(v1, v2);
console.log(v3.toString()); // "(5, 7, 9)"
console.log(v1.toString()); // "(1, 2, 3)" (원본 유지)

// --- 가변 연산 (인스턴스 메서드 사용) ---
// v1.clone을 통해 원본을 복사한 후 연산합니다.
const v4 = v1.clone.add(v2);
console.log(v4.toString()); // "(5, 7, 9)"

// 원본 v1을 직접 변경합니다. (체이닝 가능)
v1.add(v2).mulScalar(2);
console.log(v1.toString()); // "(10, 14, 18)"

// 정규화 및 길이 계산
const normalizedV1 = v1.normalized; // 새로운 정규화된 벡터 반환
const length = v1.length; // 벡터의 크기(길이) 계산

console.log(`Length: ${length}`);
console.log(`Normalized: ${normalizedV1.toString()}`);

// 내적 및 외적
const dotProduct = Vec3.dot(v1, v2);
const crossProduct = Vec3.cross(v1, v2);

console.log(`Dot Product: ${dotProduct}`);
console.log(`Cross Product: ${crossProduct.toString()}`);

Quat (쿼터니언) 및 회전

vecs-ts는 쿼터니언을 사용한 3D 회전을 완벽하게 지원합니다.

import { Vec3, Quat, RotationPriority } from 'vecs-ts';

const point = new Vec3(1, 0, 0);
const axis = new Vec3(0, 1, 0); // Y축을 기준으로 회전
const angle = Math.PI / 2; // 90도

// Y축 기준으로 90도 회전
point.rotationFromQuaternion(axis, angle);

console.log(point.round(5).toString()); // "(0, 0, -1)"

// 오일러 각도를 이용한 회전
const eulerAngles = new Vec3(0, Math.PI / 2, 0);
point.rotationFromEuler(eulerAngles, RotationPriority.YXZ);

console.log(point.round(5).toString()); // "(-1, 0, 0)"

행렬 (Matrix) 사용 예시

import { Mat3, Vec3 } from 'vecs-ts';

const m1 = new Mat3(
    1, 2, 3,
    4, 5, 6,
    7, 8, 9
);

const m2 = Mat3.identity; // 단위 행렬

// 행렬 곱셈
const m3 = Mat3.mul(m1, m2);

// 역행렬 및 전치 행렬
const invertedM1 = m1.inversed;
const transposedM1 = m1.transposed;

console.log(m1.toString());
/*
┌ 1 2 3 ┐
│ 4 5 6 │
└ 7 8 9 ┘
*/

📖 API 문서 (API Documentation)

(여기에 TypeDoc 등으로 생성된 상세 API 문서 링크를 추가할 수 있습니다.)

주요 클래스

• Vec2, IntVec2
• Vec3, IntVec3
• Vec4, IntVec4
• Quat
• Mat2
• Mat3

주요 개념

불변성(Immutability)과 가변성(Mutability)

• 정적 메서드 (Vec3.add(a, b)): 항상 새로운 인스턴스를 반환합니다. 원본 벡터는 변경되지 않아 예측 가능하고 안전한 코드를 작성할 수 있습니다.
• 인스턴스 메서드 (vec.add(otherVec)): 원본 벡터의 값을 직접 수정(mutate)하고 자기 자신을 반환하여 메서드 체이닝을 지원합니다. 성능이 중요한 경우나 명시적으로 값을 변경하고자 할 때 유용합니다.
• .clone: 인스턴스 메서드를 사용하면서 원본을 보존하고 싶을 때는 .clone 게터(getter)를 사용하여 복사본을 만든 후 연산을 수행하세요. vec.clone.add(otherVec)

속성 접근

x, y, z, w 속성과 [0], [1], [2], [3] 인덱서를 모두 사용하여 벡터의 각 요소에 접근할 수 있습니다.

const vec = new Vec3(1, 2, 3);
console.log(vec.x);   // 1
console.log(vec[0]);  // 1

📜 라이선스 (License)

This project is licensed under the MIT License.