npm package: @ngx-3d/viewport
Description: Three.js integration for Angular
Latest version: 0.1.34

# @ngx-3d/viewport

A powerful Angular library for integrating THREE.js 3D graphics into your Angular applications with ease. Built with Angular 20+ and THREE.js, this library provides a declarative, component-based approach to creating 3D scenes.

## 🚀 Features

- **Declarative Components**: Use Angular components to define 3D elements in your templates
- **Reactive State Management**: Built on @ngrx/signals for efficient state updates
- **Animation Support**: Easy-to-use animation system for 3D objects
- **Light Management**: Simple API for adding and managing lights
- **Model Loading**: Support for loading GLTF/GLB 3D models
- **Responsive Rendering**: Automatic viewport handling and responsive design
- **TypeScript**: Full TypeScript support with type definitions
- **Tree-shakeable**: Optimized bundle size with specific THREE.js imports

## 📦 Installation

```bash
npm install @ngx-3d/viewport three
npm install --save-dev @types/three
```

Or using yarn:

```bash
yarn add @ngx-3d/viewport three
yarn add --dev @types/three
```

Or using pnpm:

```bash
pnpm add @ngx-3d/viewport three
pnpm add -D @types/three
```

## 🎯 Quick Start

### 1. Import the provider in your app configuration

```typescript
import { ApplicationConfig } from '@angular/core';
import { provideN3DViewport } from '@ngx-3d/viewport';

export const appConfig: ApplicationConfig = {
  providers: [
    provideN3DViewport()
  ]
};
```

### 2. Use the components in your template

```typescript
import { Component } from '@angular/core';
import { N3DElementComponent } from '@ngx-3d/viewport';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [N3DElementComponent],
  template: `
    <n3d-element
      [modelPath]="'assets/models/scene.glb'"
      [autoRotate]="true"
      [cameraPosition]="{ x: 0, y: 5, z: 10 }"
    />
  `
})
export class AppComponent {}
```

## 📚 Components

### N3DElementComponent

The main component for rendering 3D models:

```typescript
<n3d-element
  [modelPath]="'assets/models/model.glb'"
  [scale]="2"
  [position]="{ x: 0, y: 0, z: 0 }"
  [rotation]="{ x: 0, y: Math.PI / 4, z: 0 }"
  [autoRotate]="true"
  [rotationSpeed]="1"
  [cameraPosition]="{ x: 0, y: 5, z: 10 }"
  [enableZoom]="true"
  [enablePan]="true"
  [lights]="['directional', 'ambient']"
/>
```

### N3DPlaneComponent

Add ground planes and surfaces:

```typescript
<n3d-plane
  [width]="100"
  [height]="100"
  [color]="0x999999"
  [receiveShadow]="true"
/>
```

## 🎨 State Management

Access the reactive state store:

```typescript
import { inject } from '@angular/core';
import { N3DViewportStore } from '@ngx-3d/viewport';

export class MyComponent {
  store = inject(N3DViewportStore);

  // Access reactive state
  scene = this.store.scene;
  camera = this.store.camera;
  renderer = this.store.renderer;
  
  // Get current values
  currentScene = this.store.scene();
}
```

## 🏗️ Development

### Building the Library

```bash
cd projects/viewport
npm run build
```

Build artifacts will be placed in `dist/ngx-3d-viewport/`.

### Development Mode

```bash
npm run build:watch
```

### Publishing

1. Build the library:
   ```bash
   npm run build
   ```

2. Navigate to the dist directory:
   ```bash
   cd dist/ngx-3d-viewport
   ```

3. Publish to npm:
   ```bash
   npm publish
   ```

## 📋 Requirements

- Angular 20.3.0 or higher
- THREE.js 0.181.0 or higher
- @types/three (for TypeScript support)
- TypeScript 5.9.0 or higher

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT License

## 🔗 Links

- [Angular](https://angular.dev)
- [THREE.js](https://threejs.org)
- [Documentation](https://github.com/elkestudio/n3d)