npm package: @preference-sl/pref-gltf-transform
Description: Web component to complete GLTF
Latest version: 1.0.6

# @preference-sl/pref-gltf-transform

Helper utilities built on top of [glTF Transform](https://gltf-transform.dev/) to process glTF assets in the browser.

Features:
- **Complete GLTF**: Pack a `.gltf` and its external buffers into a single `.gltf` file.
- **Caching**: Uses IndexedDB to cache large binary assets to avoid re-downloading.

## Installation

```bash
npm install @preference-sl/pref-gltf-transform
```

## Usage

### 1. Import in Modern Bundlers (Vite, Webpack, etc.)

```javascript
import {
  completeModelGLTF
} from '@preference-sl/pref-gltf-transform';

// ... usage
```

### 2. Import in Browser (without bundler)

Browsers require an **Import Map** to resolve the package name if you are not using a build tool.

**index.html**:
```html
<script type="importmap">
{
  "imports": {
    "@preference-sl/pref-gltf-transform": "./node_modules/@preference-sl/pref-gltf-transform/www/pref-gltf-transform.js"
  }
}
</script>
<script type="module">
  import { LoadModelGLTF } from '@preference-sl/pref-gltf-transform';
</script>
```

## API

```ts
completeModelGLTF(gltfUrl: string, kbUrl: string): Promise<string>
```

---

## Parameters

### `gltfUrl: string`

URL to the original (incomplete) `.gltf` file.

- The file may reference external `.bin` buffers
- The JSON may be loaded from cache or fetched from the network

---

### `kbUrl: string`

Host (or `host:port`) of the KB server where external buffers (parts) are stored.

- HTTPS protocol is automatically used
- Examples:
  - `example.com`
  - `example.com:8443`

---

## Returns

### `Promise<string>`

A **Blob URL** (`blob:...`) pointing to the completed GLTF file with all referenced buffers embedded as Base64 data URIs.

---

## External Buffer URI (Path Support)

This component supports glTF assets that reference external .bin buffers using absolute file or web url paths, e.g.:

```json
"uri": "c:\\kb_output\\Reynaers\\part\\0696831.bin"
"uri": "https://stg.prefweb.com/Deceuninck/prefweb/Images/Textures/kb/deceuninck/part/0696831.bin"
```

## Convert GLTF to GLB

1) Install gltf-transform
```bash
npm install --global @gltf-transform/cli
```

2) Convert GLTF to GLB
```bash
gltf-transform copy input.gltf output.glb
```

---

## Development

If you want to contribute or modify this package:

### Build
Compiles TypeScript to JavaScript (`www/pref-gltf-transform.js`) and generates types (`www/pref-gltf-transform.d.ts`).

```bash
npm run build
```

### Test
Runs the verification script in the `playground/` directory.

```bash
npm test
```

### Playground
A local test environment is available in `playground/`.
1. Build the project: `npm run build`
2. Pack it: `npm pack`
3. Go to playground: `cd playground`
4. Install tarball: `npm install ../preference-sl-pref-gltf-transform-1.0.0.tgz`
5. Run server: `npx serve .`

## Publishing

1. Increment version in `package.json`.
2. Run the release script:
   ```bash
   npm run release
   ```

The script will automatically:
- Run `npm run build`
- Publish to npm with public access
- Handle errors gracefully