# i3viewer

> 轻量化3维引擎

Latest version **0.5.22** (published 2025-03-25) · 0 weekly downloads

## Install

```sh
npm install i3viewer
pnpm add i3viewer
yarn add i3viewer
bun add i3viewer
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.5.22 |
| Published | 2025-03-25 |
| First published | 2023-06-12 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 15 |
| Unpacked size | 4.7 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Billy Chen |
| Maintainers | billy2008 |
| Keywords | 3d |

## Links

- npm: https://www.npmjs.com/package/i3viewer
- npm.io page: https://npm.io/package/i3viewer

## Dependencies (15)

- [idb](https://npm.io/package/idb.md) ^7.1.1
- [jszip](https://npm.io/package/jszip.md) ^3.10.1
- [three](https://npm.io/package/three.md) ^0.158.0
- [cesium](https://npm.io/package/cesium.md) ^1.110.0
- [dat.gui](https://npm.io/package/dat.gui.md) ^0.7.9
- [cash-dom](https://npm.io/package/cash-dom.md) ^8.1.5
- [stats-js](https://npm.io/package/stats-js.md) ^1.0.1
- [color-name](https://npm.io/package/color-name.md) ^2.0.0
- [detect-gpu](https://npm.io/package/detect-gpu.md) ^5.0.37
- [ua-parser-js](https://npm.io/package/ua-parser-js.md) ^1.0.35
- [@zip.js/zip.js](https://npm.io/package/@zip.js/zip.js.md) ^2.7.20
- [notice-message](https://npm.io/package/notice-message.md) ^1.1.1
- [@simonwep/pickr](https://npm.io/package/@simonwep/pickr.md) ^1.8.2
- [polygon-clipping](https://npm.io/package/polygon-clipping.md) ^0.15.7
- [@tweenjs/tween.js](https://npm.io/package/@tweenjs/tween.js.md) ^21.0.0

## Recent versions

- 0.5.22 (latest) — 2025-03-25
- 0.5.21 — 2024-09-24
- 0.5.20 — 2024-09-02
- 0.5.19 — 2024-08-21
- 0.5.18 — 2024-07-29
- 0.5.17 — 2024-07-23
- 0.5.16 — 2024-06-19
- 0.5.15 — 2024-06-18
- 0.5.14 — 2024-05-24
- 0.5.12 — 2024-04-19
- 0.5.11 — 2024-04-10
- 0.5.10 — 2024-04-10
- 0.5.9 — 2024-04-03
- 0.5.8 — 2023-12-26
- 0.5.7 — 2023-10-09
- … 54 more at https://npm.io/package/i3viewer/versions

## README

<!--
 * @Author: Billy
 * @Date: 2023-05-17 08:58:31
 * @LastEditors: Billy
 * @LastEditTime: 2023-06-09 16:33:27
 * @Description: 请输入
-->

# 🔨 示例
## VUE
### 使用官方模型示例
```html
<template><div class="home" ref="home"></div></template>
<script>
import { Viewer, Setting, Examples } from "i3viewer";
export default {
  mounted() {
    const settings = new Setting({ camInitDirection: [1, 1, 1], sceneBgColor: 0xffffff });
    const viewer = new Viewer(this.$refs["home"], settings);
    new Examples.SmallCity(viewer).load();
  },
};
</script>
<style lang="scss" scoped>
.home {
  width: 100%;
  height: 100%;
}
</style>
```

### 加载后端模型数据
```html
<template>
  <div class="home" ref="home"></div>
</template>

<script>
import { Viewer, Setting, Model, Source } from "i3viewer";

const modelUrl = `http://220.168.85.72:10000/i3viewer/mdsbk/40287e0289f801050189f80105db0000_LOD0.zip`;
const infoUrl = `http://220.168.85.72:10000/i3viewer/mdsbk/40287e0289f801050189f80105db0000_json.zip`;
const metaUrl = `http://220.168.85.72:10000/i3viewer/mdsbk/40287e0289f801050189f80105db0000_metadata.zip`;

export default {
  mounted() {
    const settings = new Setting({
      camInitDirection: [1, 1, 1],
      sceneBgColor: 0xffffff,
    });

    const viewer = new Viewer(this.$refs["home"], settings);

    const models = [
      new Model({
        id: "40287e0289f801050189f80105db0000",
        modelSrc: new Source({ url: modelUrl }),
        infoSrc: new Source({ url: infoUrl }),
        metaSrc: new Source({ url: metaUrl }),
      }),
    ];

    viewer.load(models);
  },
};
</script>

<style lang="scss" scoped>
.home {
  width: 100%;
  height: 100%;
}
</style>
```
---
# 🔠 类型
## Viewer 三维浏览器类
### 属性
| 属性名         | 类型                                                       | 描述                           |
|----------------|------------------------------------------------------------|--------------------------------|
| isModelLoading | boolean                                                    | 模型是否正在下载或加载中       |
| setting        | [Setting](#setting-设置类)                                 | 获取设置信息                   |
| boundingBox    | Object                                                     | 获取当前所有模型的总包围盒     |
| boundingSphere | Object                                                     | 获取当前所有模型的总包围球     |
| dataHelper     | [DataHelper](#datahelper-数据辅助类)                       | 数据相关辅助方法               |
| operaHelper    | [OperaHelper](#operahelper-操作辅助类)                     | 操作相关辅助方法               |
| settingHelper  | [SettingHelper](#settinghelper-设置辅助类)                 | 设置相关辅助方法               |
| controlsHelper | [ControlsHelper](#controlshelper-轨道控制器辅助类)         | 轨道控制器辅助方法             |
| currSelected   | [ThingContainerShell](#thingcontainershell-组件信息集合类) | 获取当前被选中的构件的业务信息 |

### 构造方法
#### constructor(dom: HTMLElement, setting?: Setting);
* outerContainer: 需要加载 Viewer 的 dom 容器
* setting: (可选) 设置项

### 实例方法

#### load(models: Array<Model>): Promise<Monitor>;
> [加载模型](#加载后端模型数据)

#### on(eventName: string, fn: (data?: any) => void): Viewer;
> 监听事件的方法

* eventName: 事件名称
* fn: 事件回调

#### off(eventName: string, fn: (data?: any) => void): Viewer;
> 解除事件监听的方法

* eventName: 事件名称
* fn: 之前注册过的事件回调

#### updateSize(): void;
> 根据 Viewer 所在 DOM 容器的尺寸更新 Viewer 尺寸(不会触发 viewer-resized 事件)

### 事件
| 事件名         | 解释                             | 参数                 |
|----------------|----------------------------------|----------------------|
| viewer-resized | 模型视口尺寸改变并更新模型位置后 | -                    |
| model-loaded   | 模型加载后触发                   | 被加载的模型信息对象 |

> 单击、双击等[更多事件](https://gitee.com/bi2008/i3viewer-manual/blob/master/more/viewer-more.md#%E4%BA%8B%E4%BB%B6)

---
## DataHelper 数据辅助类
[点此跳转](https://gitee.com/bi2008/i3viewer-manual/blob/master/data-helper.md)

## OperaHelper 操作辅助类
[点此跳转](https://gitee.com/bi2008/i3viewer-manual/blob/master/opera-helper.md)

## SettingHelper 设置辅助类
[点此跳转](https://gitee.com/bi2008/i3viewer-manual/blob/master/setting-helper.md)

## ControlsHelper 轨道控制器辅助类
[点此跳转](https://gitee.com/bi2008/i3viewer-manual/blob/master/controls-helper.md)

---
## Setting 设置类
### 属性
| 属性名              | 类型                                | 默认值    | 描述                                                            |
|---------------------|-------------------------------------|-----------|-----------------------------------------------------------------|
| camInitDirection    | [number, number, number]            | [1, 1, 1] | 初始的摄像头方位(顺序xyz)                                       |
| upAxis              | 'X', 'Y', 'Z'                       | 'Y'       | 设置朝向上的轴                                                  |
| sceneBgColor        | number                              | 0x000000  | 场景背景色(16进制数字)                                          |
| axesHelperMultiples | number                              | 0         | 3色坐标与场景包围盒尺寸的比例(为0时无3色坐标)                   |
| toolBarSetting      | [IToolBarSetting](#itoolbarsetting) | undefined | 对工具条的设置                                                  |
| useCache            | 'none', 'parsed', 'final'           | 'none'    | 是否缓存模型数据到本地(parsed 缓存中间过程, final 缓存最终结果) |
| isOutlineDrawn      | boolean                             | false     | 是否描边                                                        |
| outlineColorHex     | number                              | 0x000000  | 描边的颜色(16进制数字)                                          |

## Model 模型类
### 属性
| 属性名   | 类型                         | 默认值    | 描述                 |
|----------|------------------------------|-----------|----------------------|
| id       | string                       | ''        | 模型全局唯一id       |
| prefix   | string                       | ''        | 指定 bizId 的前缀    |
| modelSrc | [Source](#source-模型来源类) | 必传      | 模型三维数据获取地址 |
| infoSrc  | [Source](#source-模型来源类) | undefined | 模型额外信息获取地址 |
| compSrc  | [Source](#source-模型来源类) | undefined | 模型构件信息获取地址 |

## Source 模型来源类
### 属性
| 属性名 | 类型                           | 描述       |
|--------|--------------------------------|------------|
| url    | string                         | 资源地址   |
| method | 'GET', 'POST'                  | 下载方法   |
| token  | [Token](#token-模型来源凭证类) | 请求 Token |

## Token 模型来源凭证类
### 属性
| 属性名   | 类型                      | 描述             |
|----------|---------------------------|------------------|
| value    | string                    | token 的值       |
| key      | 'GET', 'POST'             | token 的键       |
| position | 'header', 'query', 'body' | token 的传输方式 |

## Transform 移动、旋转、缩放类
### 属性
| 属性名   | 类型                     | 默认值             | 描述                     |
|----------|--------------------------|--------------------|--------------------------|
| id       | string                   | -                  | -                        |
| position | [Point](#point-位置向量) | new Point(0, 0, 0) | 位置，单位：默认长度单位 |
| rotation | [Point](#point-位置向量) | new Point(0, 0, 0) | 旋转，单位：弧度         |
| scale    | [Point](#point-位置向量) | new Point(1, 1, 1) | 缩放，单位：缩放的倍数   |

## Point 位置/向量
### 属性
| 属性名 | 类型   | 默认值 | 描述     |
|--------|--------|--------|----------|
| x      | number | 0      | x 轴数值 |
| y      | number | 0      | y 轴数值 |
| z      | number | 0      | z 轴数值 |

---
## IToolBarSetting 
| 属性名   | 类型     | 默认值    | 描述                                     |
|----------|----------|-----------|------------------------------------------|
| rowCount | number   | 1         | 工具条分多少行                           |
| include  | string[] | undefined | 包含哪些按钮(若为空数组，则工具条不显示) |
| exclude  | string[] | undefined | 不包含哪些按钮                           |

## Examples 可选模型库
| 模型类名                  | 描述         |
|---------------------------|--------------|
| Examples.SmallCity        | 小城市       |
| Examples.Building         | 小区排楼     |
| Examples.BlueHouse        | 小别墅       |
| Examples.ResidentalHouse  | 花园别墅     |
| Examples.TwoStoryHouse    | 二层独栋别墅 |
| Examples.SimpleGeomatry01 | 立方体和球体 |

---
## ThingContainerShell 组件信息集合类
### 实例方法
#### on(eventName: string, fn: (data?: any) => void): ThingContainerShell;
> 监听事件的方法

* eventName: 事件名称
* fn: 事件回调

#### off(eventName: string, fn: (data?: any) => void): ThingContainerShell;
> 解除事件监听的方法

* eventName: 事件名称
* fn: 之前注册过的事件回调

#### get length(): number;
> 获取构件的个数

#### getAll(): Array\<BizInfo>;
> 获取所有相关构件的业务数据

#### empty(): void;
> 清除所有相关构件

### 事件
| 事件名 | 解释                         | 参数                             |
|--------|------------------------------|----------------------------------|
| add    | 添加一个或多个键值对之后触发 | [BizInfo](#bizinfo-组件业务数据) |
| del    | 删除一个或多个键值对之后触发 | [BizInfo](#bizinfo-组件业务数据) |

### BizInfo 组件业务数据
| 属性名  | 类型   | 描述    |
|---------|--------|---------|
| innerId | number | 内置 id |
| bizId   | string | 组件 id |
| modelId | number | 模型 id |

### 示例
#### 获取当前被选中的构件的业务信息
```javascript
// 监听当前新增选中的构件的业务信息
viewer.currSelected.on("add", (bizInfos) => {
  console.log("bizInfos adding:>> ", bizInfos);
});

// 监听当前取消选中的构件的业务信息
viewer.currSelected.on("del", (bizInfos) => {
  console.log("bizInfos deleting:>> ", bizInfos);
});

// 获取当前选中的所有构件的业务信息
const bizInfos = viewer.currSelected.getAll();
console.log("current bizInfos:>> ", bizInfos);

```
---

# 🔌 插件开发
[点此跳转](https://gitee.com/bi2008/i3viewer-manual/blob/master/more/plugin.md)

# 🛠️ 更多示例
[点此跳转](https://gitee.com/bi2008/i3viewer-manual/blob/master/more/more-example.md)

---
_Source: https://npm.io/package/i3viewer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._