# mat4

**Repository Path**: cesiumjs/mat4

## Basic Information

- **Project Name**: mat4
- **Description**: A library for handling 4x4 matrix operations including transformations, rotations, scaling, and projections.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-16
- **Last Updated**: 2025-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mat4.js

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cesiumjs/mat4.js/blob/main/LICENSE)  
[![npm version](https://img.shields.io/npm/v/mat4.js.svg)](https://www.npmjs.com/package/mat4.js)

A TypeScript library for handling 4x4 matrix operations including transformations, rotations, scaling, and projections.

---

## Features

- **Multiple Module Formats**: Supports ESM, CommonJS, and UMD formats, compatible with Node.js and browser environments.
- **Matrix Operations**: Includes common matrix operations such as addition, subtraction, multiplication, inversion, and transposition.
- **Transformations**: Provides functions for translation, scaling, and rotation around any axis.
- **Projection Matrices**: Supports perspective and orthographic projection matrices.
- **View Matrices**: Generates Look-at matrices for camera positioning.
- **Utility Functions**: Offers tools for matrix decomposition, comparison, and string representation.
- **Performance Optimized**: Designed for efficient mathematical computations in intensive scenarios.

---

## Installation

Install via npm:

```bash
npm install mat4.js
```

Or using Yarn:

```bash
yarn add mat4.js
```

---

## Usage

### Importing the Library

#### ESM (Recommended for Modern JavaScript Environments)

```javascript
import * as mat4 from 'mat4.js';

// Create an identity matrix
const matrix = mat4.create();
console.log(matrix);
```

#### CommonJS (For Node.js Environments)

```javascript
const mat4 = require('mat4.js');

// Create an identity matrix
const matrix = mat4.create();
console.log(matrix);
```

#### Browser Environment (Using `<script>` Tag)

You can include the UMD build in your HTML file:

```html
<script src="https://unpkg.com/mat4.js/dist/umd/index.js"></script>
<script>
  // Use the global variable [mat4](gl-matrix\src\types.d.ts#L26-L31)
  const matrix = mat4.create();
  console.log(matrix);
</script>
```

---

### Example: Creating a Perspective Projection Matrix

```javascript
import { perspective, create,printMatrix } from 'mat4.js';

// Create a new matrix
const projMatrix = create();

// Set up perspective projection parameters
mat4.perspective(projMatrix, Math.PI / 4, 16 / 9, 0.1, 1000.0);
printMatrix(projMatrix);
```

---

### Example: Matrix Multiplication

```javascript
import { create, multiply } from 'mat4.js';

// Create two matrices
const matA = create();
const matB = create();

// Multiply them
const result = create();
multiply(result, matA, matB);

console.log(result);
```

---

### Example: Look-at Matrix

```javascript
import { lookAt, create } from 'mat4.js';

// Define eye position, target point, and up vector
const eye = [0, 0, 5];
const center = [0, 0, 0];
const up = [0, 1, 0];

// Generate Look-at matrix
const viewMatrix = create();
lookAt(viewMatrix, eye, center, up);

console.log(viewMatrix);
```
---

### Example: Prints a mat4 matrix in a human-readable row-by-column format.

```javascript
import { lookAt, create,printMatrix } from 'mat4.js';

// Define eye position, target point, and up vector
const eye = [0, 0, 5];
const center = [0, 0, 0];
const up = [0, 1, 0];

// Generate Look-at matrix
const viewMatrix = create();
lookAt(viewMatrix, eye, center, up);
printMatrix(viewMatrix)
```

---

## API Reference

Below is a list of core functions provided by the library:

- **Matrix Creation**: [[create](mat4\src\index.ts#L11-L18)](mat4\src\index.ts#L11-L18), [[clone](mat4\src\index.ts#L26-L45)](mat4\src\index.ts#L26-L45), [[fromValues](mat4\src\index.ts#L95-L131)](mat4\src\index.ts#L95-L131)
- **Matrix Manipulation**: [[identity](mat4\src\index.ts#L199-L217)](mat4\src\index.ts#L199-L217), [[transpose](mat4\src\index.ts#L226-L268)](mat4\src\index.ts#L226-L268), [[invert](mat4\src\index.ts#L277-L335)](mat4\src\index.ts#L277-L335), [[adjoint](mat4\src\index.ts#L344-L392)](mat4\src\index.ts#L344-L392)
- **Matrix Transformations**: [[translate](mat4\src\index.ts#L506-L553)](mat4\src\index.ts#L506-L553), [[scale](mat4\src\index.ts#L563-L585)](mat4\src\index.ts#L563-L585), [[rotate](mat4\src\index.ts#L596-L668)](mat4\src\index.ts#L596-L668), [[rotateX](mat4\src\index.ts#L678-L712)](mat4\src\index.ts#L678-L712), [[rotateY](mat4\src\index.ts#L722-L756)](mat4\src\index.ts#L722-L756), [[rotateZ](mat4\src\index.ts#L766-L800)](mat4\src\index.ts#L766-L800)
- **Projection Matrices**: [[perspective](twgl.js\src\m4.js#L508-L535)](mat4\src\index.ts#L1547-L1574), [[ortho](twgl.js\src\m4.js#L553-L577)](mat4\src\index.ts#L1584-L1608), [[frustum](mat4\src\index.ts#L1487-L1508)](mat4\src\index.ts#L1487-L1508)
- **View Matrices**: [[lookAt](mat4\src\index.ts#L1724-L1802)](mat4\src\index.ts#L1724-L1802), [[targetTo](mat4\src\index.ts#L1813-L1862)](mat4\src\index.ts#L1813-L1862)
- **Matrix Arithmetic**: [[add](mat4\src\index.ts#L1943-L1961)](mat4\src\index.ts#L1943-L1961), [[subtract](mat4\src\index.ts#L1971-L1989)](mat4\src\index.ts#L1971-L1989), [[multiply](mat4\src\index.ts#L441-L496)](mat4\src\index.ts#L441-L496), [[multiplyScalar](mat4\src\index.ts#L1999-L2017)](mat4\src\index.ts#L1999-L2017)
- **Comparison Utilities**: [[equals](mat4\src\index.ts#L2083-L2152)](mat4\src\index.ts#L2083-L2152), [[exactEquals](mat4\src\index.ts#L2055-L2074)](mat4\src\index.ts#L2055-L2074)
- **Decomposition**: [[decompose](mat4\src\index.ts#L1222-L1285)](mat4\src\index.ts#L1222-L1285), [[getTranslation](mat4\src\index.ts#L1118-L1124)](mat4\src\index.ts#L1118-L1124), [[getScaling](mat4\src\index.ts#L1136-L1152)](mat4\src\index.ts#L1136-L1152), [[getRotation](mat4\src\index.ts#L1163-L1211)](mat4\src\index.ts#L1163-L1211)
- **String Representation**: [[str](mat4\src\index.ts#L1870-L1906)](mat4\src\index.ts#L1870-L1906)

For detailed documentation, refer to the [source code](https://gitee.com/cesiumjs/mat4).

---

## Building from Source

### Clone the Repository

```bash
git clone https://gitee.com/cesiumjs/mat4.git
cd mat4
```

### Install Dependencies

```bash
npm install
```

### Build the Library

```bash
npm run build
```

The output files will be generated in the `dist` directory, including:
- `index.js` (CommonJS format)
- `index.mjs` (ESM format)
- `umd/index.js` (UMD format for browsers)

---

## Contributing

Contributions are welcome! Please follow these steps:
1. Fork the repository.
2. Create a new branch (`git checkout -b feature/my-feature`).
3. Commit your changes (`git commit -m "Add my feature"`).
4. Push to the branch (`git push origin feature/my-feature`).
5. Open a pull request.

---

## License

This project is licensed under the [MIT License](LICENSE).

---

For more details, visit the [repository](https://gitee.com/cesiumjs/mat4).