> **本文回答**：图像由 `ImageSource`（图像源，注册到 `Engine.activeDocument.images`）+ `ImageRefEnt`（图像引用，是真正放在图纸里的实体）组成；`new ImageRefEnt([x, y], rotation, scale)`，再 `imgRef.setImageSource(source)`，最后 `Engine.addEntities(imgRef)`。

## 一、完整流程（base64 → ImageSource → ImageRefEnt）

```js
const { Engine, ImageRefEnt, ImageSource } = vjcad;

// 1. 准备图像数据：可以是 base64，也可以走文件 / URL（按 ImageSource 文档）
const canvas = document.createElement('canvas');
canvas.width = 60; canvas.height = 40;
const ctx = canvas.getContext('2d');
// 画点东西...
const base64Data = canvas.toDataURL('image/png').split(',')[1];

// 2. 创建并初始化 ImageSource
const imgSource = new ImageSource('DemoImage', 'image/png', base64Data);
await imgSource.initTexture();

// 3. 注册到当前文档的 images 集合
Engine.activeDocument.images.add(imgSource);

// 4. 创建 ImageRefEnt 并绑定 ImageSource
const imgRef = new ImageRefEnt([insertX, insertY], 0, 1);
//                              ^插入点          ^旋转 ^比例
imgRef.setImageSource(imgSource);
imgRef.setDefaults();

Engine.addEntities(imgRef);
```

MCP 参考：`vjcad/example/entity/all/01entities.js`、`vjcad/example/entity/image/01create.js`、`vjcad/doc/entity/image-ent.md`。

## 二、关键 API

| 类 / 方法 | 说明 |
|---|---|
| `new ImageSource(name, mimeType, base64Data)` | 创建图像源 |
| `imageSource.initTexture()` | 异步初始化 GPU 纹理（必须 `await`） |
| `Engine.activeDocument.images.add(imgSource)` | 注册到当前文档 |
| `new ImageRefEnt([x, y], rotation, scale)` | 创建图像引用 |
| `imgRef.setImageSource(imgSource)` | 关联图像源 |

## 三、命名差异（来源对照）

| 命名 | 出处 |
|---|---|
| `ImageEnt` | `vjcad/doc/command/api-reference.md`（实体类型表；注意 vjcad@1.0.16 包只导出 `ImageRefEnt`，`ImageEnt` 是文档旧名） |
| `ImageRefEnt` | `vjcad/doc/guide/architecture.md`（架构图）、`vjcad/example/entity/all/01entities.js`、`vjcad/example/entity/image/01create.js` |

> 实战写代码用示例里的 **`ImageRefEnt`**（更可靠）。

## 反例

- 没 `await imageSource.initTexture()` 直接 `Engine.addEntities(imgRef)`：纹理还没准备好，画出来是空白。
- 没注册到 `Engine.activeDocument.images`：保存 / 重新打开后图像丢失。
- `ImageRefEnt` 的第三参当像素值：实际是缩放比例（`scale = 1` 表示按 ImageSource 的真实尺寸），具体单位映射可看 [doc image-ent.md]。

## 参考（官方文档 MCP）

- 文档：`vjcad/doc/entity/image-ent.md`、`vjcad/doc/guide/architecture.md`
- 示例：`vjcad/example/entity/all/01entities.js`、`vjcad/example/entity/image/01create.js`