@vicimpa/lib-vec2

Библиотека @vicimpa/lib-vec2 предоставляет обширный набор утилит для работы с 2D-векторами. Эта библиотека особенно полезна для графических приложений, симуляций физики и любых других областей, где требуется математика 2D-векторов.

Установка

Чтобы использовать библиотеку Vec2, вам нужно импортировать её в ваш TypeScript проект:

import { Vec2 } from "@vicimpa/lib-vec2";

Класс Vec2

Класс Vec2 представляет 2D-вектор и предоставляет различные методы для операций с векторами.

Конструктор

Конструктор может принимать различные типы параметров для инициализации вектора:

const v1 = new Vec2(); // По умолчанию (0, 0)
const v2 = new Vec2(1, 2); // Из координат
const v3 = new Vec2({ x: 3, y: 4 }); // Из объекта
const v4 = new Vec2(v2); // Из другого Vec2
const v5 = new Vec2("1:2"); // Из строки Vec2Hash

Создать новый вектор можно и при помощи функции: vec2

import { vec2 } from "@vicimpa/lib-vec2";
const v1 = vec2(); // По умолчанию (0, 0)
const v2 = vec2(1, 2); // Из координат
const v3 = vec2({ x: 3, y: 4 }); // Из объекта
const v4 = vec2(v2); // Из другого Vec2
const v5 = vec2("1:2"); // Из строки Vec2Hash

Свойства

• x: number - Координата x вектора.
• y: number - Координата y вектора.
• tuple: [number, number] - Возвращает вектор в виде кортежа.
• size: { width: number, height: number } - Возвращает вектор в виде объекта размера.
• point: { x: number, y: number } - Возвращает вектор в виде объекта точки.
• hash: string - Возвращает хэш вектора в формате ${x}:${y}.

Методы

Основные операции

Эти методы имеют перегрузки, которые позволяют принимать различные типы параметров:

• set(...args: Vec2Args): this
• plus(...args: Vec2Args): this
• minus(...args: Vec2Args): this
• times(...args: Vec2Args): this
• div(...args: Vec2Args): this
• rem(...args: Vec2Args): this
• pow(...args: Vec2Args): this

Утилитарные методы

• round(): this - Округляет координаты вектора.
• ceil(): this - Приводит координаты вектора к ближайшему большему целому.
• floor(): this - Приводит координаты вектора к ближайшему меньшему целому.
• inverse(): this - Меняет местами координаты x и y.
• lerp(to: Vec2, i: number): this - Линейно интерполирует между этим вектором и другим.
• sign(): this - Устанавливает координаты вектора в их знаковое значение.
• abs(): this - Устанавливает координаты вектора в их абсолютные значения.
• clone(): Vec2 - Возвращает клон вектора.
• length(): number - Возвращает длину вектора.
• distance(...args: Vec2Args): number - Возвращает расстояние до другого вектора.
• normalize(): this - Нормализует вектор.
• min(): number - Возвращает минимальную координату.
• max(): number - Возвращает максимальную координату.
• toObject(o: Vec2Point): this - Копирует координаты вектора в объект.
• toObjectSize(o: Vec2Size): this - Копирует координаты вектора в объект размера.
• toRect(...args: Vec2Args): DOMRect - Возвращает DOMRect от вектора до заданных координат.
• dotProduct(to: Vec2): number - Возвращает результат скалярного произведения векторов.
• projectScalar(to: Vec2): number - Возвращает результат проецирования векторов.

Методы с префиксом c

Эти методы создают клон вектора, выполняют операцию над клоном и возвращают новый вектор. Это полезно, когда нужно сохранить исходный вектор неизменным.

• cplus(...args: Vec2Args): Vec2 - Возвращает новый вектор, который является результатом сложения текущего вектора с заданными аргументами.
• cminus(...args: Vec2Args): Vec2 - Возвращает новый вектор, который является результатом вычитания заданных аргументов из текущего вектора.
• ctimes(...args: Vec2Args): Vec2 - Возвращает новый вектор, который является результатом умножения текущего вектора на заданные аргументы.
• cdiv(...args: Vec2Args): Vec2 - Возвращает новый вектор, который является результатом деления текущего вектора на заданные аргументы.
• crem(...args: Vec2Args): Vec2 - Возвращает новый вектор, который является результатом операции остатка от деления текущего вектора на заданные аргументы.
• cpow(...args: Vec2Args): Vec2 - Возвращает новый вектор, который является результатом возведения текущего вектора в степень, заданную аргументами.
• cinverse(): Vec2 - Возвращает новый вектор, который является результатом инверсии координат текущего вектора.
• cnormalize(): Vec2 - Возвращает новый вектор, который является нормализованной версией текущего вектора.
• clerp(to: Vec2, i: number): Vec2 - Возвращает новый вектор, который является результатом линейной интерполяции между текущим вектором и заданным.
• csign(): Vec2 - Возвращает новый вектор, координаты которого установлены в их знаковое значение.
• cabs(): Vec2 - Возвращает новый вектор, координаты которого установлены в их абсолютные значения.
• cround(): Vec2 - Возвращает новый вектор, координаты которого округлены.
• cceil(): Vec2 - Возвращает новый вектор, координаты которого приведены к ближайшему большему целому.
• cfloor(): Vec2 - Возвращает новый вектор, координаты которого приведены к ближайшему меньшему целому.

Статические методы

• fromRandom(vec?: Vec2): Vec2 - Создает или обновляет вектор из рандомного числа от 0 до 1.
• fromSrandom(vec?: Vec2): Vec2 - Создает или обновляет вектор из рандомного числа от -1 до 1.
• fromHash(hash: Vec2Hash, vec?: Vec2): Vec2 - Создает или обновляет вектор из хэша.
• fromAngle(d: number, vec?: Vec2): Vec2 - Создает или обновляет вектор из угла.
• fromPoint(point: Vec2Point, vec?: Vec2): Vec2 - Создает или обновляет вектор из точки.
• fromSize(size: Vec2Size, vec?: Vec2): Vec2 - Создает или обновляет вектор из размера.
• fromDeltaXY(delta: TDeltaXY, vec?: Vec2): Vec2 - Создает или обновляет вектор из значений дельты.
• fromPageXY(page: TPageXY, vec?: Vec2): Vec2 - Создает или обновляет вектор из координат страницы.
• fromOffsetXY(offset: TOffsetXY, vec?: Vec2): Vec2 - Создает или обновляет вектор из смещенных координат.
• fromOffsetSize(elem: HTMLElement, vec?: Vec2): Vec2 - Создает или обновляет вектор из размера элемента.
• fromSvgLength(x: SVGAnimatedLength, y: SVGAnimatedLength, vec?: Vec2): Vec2 - Создает или обновляет вектор из длин SVG.

Примеры

Основное использование

import { Vec2 } from "@vicimpa/lib-vec2";

const v1 = new Vec2(1, 2);
const v2 = new Vec2(3, 4);

v1.plus(1, 1); // v1 теперь (2, 3)
v2.minus(v1); // v2 теперь (1, 1)

console.log(v1.length()); // Выводит длину v1
console.log(v2.distance(v1)); // Выводит расстояние между v2 и v1

Использование с Canvas

Библиотека также предоставляет патчи для CanvasRenderingContext2D и Path2D, чтобы они принимали экземпляры Vec2 напрямую.

import { Vec2 } from "@vicimpa/lib-vec2";

const canvas = document.getElementById("myCanvas") as HTMLCanvasElement;
const ctx = canvas.getContext("2d");

const start = new Vec2(50, 50);
const end = new Vec2(200, 200);

ctx.moveTo(start);
ctx.lineTo(end);
ctx.stroke();

Продвинутые операции

import { Vec2 } from "@vicimpa/lib-vec2";

const v1 = new Vec2(1, 2);
const v2 = new Vec2(3, 4);

const v3 = v1.clone().plus(v2); // v3 теперь (4, 6)
const v4 = Vec2.fromAngle(Math.PI / 4); // v4 примерно (0.707, 0.707)

console.log(v3.toString()); // Выводит "4 6"
console.log(v4.toString()); // Выводит "0.707 0.707"