# bookcover-3d-web 中文文档

规范地址：https://npmcn.com/package/bookcover-3d-web/

版本：0\.24\.0
npm 元数据更新时间：2026-11-03T04:33:11.741Z
中文译文更新时间：2026-11-03T06:07:11.887Z
软件包许可：MIT-0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/bookcover-3d-web
原文对照：https://npmcn.com/package/bookcover-3d-web/?lang=original
项目主页：https://github.com/gracious-tech/bookcover/tree/main/3d#readme
源码仓库：https://github.com/gracious-tech/bookcover

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：73.1 kB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-07-16T12:22:17.435Z
- 最新版本发布：2026-11-03T04:33:11.587Z
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

通过提供书籍封面设计，创建书籍的3D图像。部分 [封套](https://github.com/gracious-tech/bookcover) 一代系统。

## 安装

```sh
npm install bookcover-3d-web
```

也可以使用：`pnpm add bookcover-3d-web`、`yarn add bookcover-3d-web`、`bun add bookcover-3d-web`

## README

# bookcover-3d-web

通过提供书籍封面设计，创建书籍的3D图像。部分 [封套](https://github.com/gracious-tech/bookcover) 一代系统。

```
npm install bookcover-3d-web
```

![Example 3D image](https://npmcn.com/package/bookcover-3d-web/README_sample.webp)

这是一个WebGL 3D图书渲染器，没有外部图形依赖。

```ts
import {Book3DRenderer, generate} from 'bookcover-3d-web'
import type {BookFaces, CoverType, GenerateOptions} from 'bookcover-3d-web'
```

两个导出都采用相同的SVG面输入并产生相同类型的输出。这个 区别在于生命周期： `generate` 创建和销毁的一次性帮助器是 渲染器内部，while `Book3DRenderer` 保持WebGL上下文存活，这样你就可以 低成本地重新渲染（例如，鼠标拖动），而无需重新加载纹理。

使用 `generate` 用于静态导出。使用 `Book3DRenderer` 交互式预览。

## `generate(svgs, options?): Promise<Uint8Array>`

创建一个渲染器，加载svg，渲染一次，返回PNG字节，然后清理。

```ts
import {generate} from 'bookcover-3d-web'

const png = await generate(
    {front: frontSvg, back: backSvg, spine: spineSvg},
    {cover_type: 'paperback', azimuth: -30, width: 800, height: 600},
)
```

```ts
interface BookFaces {
    front: string   // SVG string
    back: string    // SVG string
    spine?: string  // SVG string (optional — depth_mm used if absent)
}

interface GenerateOptions {
    cover_type?: 'paperback'|'paperback_coil'|'paperback_wire'|'paperback_stitch'|'hardcover'|'hardcover_jacket'
    azimuth?: number     // horizontal camera angle in degrees (default: -30)
    elevation?: number   // vertical camera angle in degrees (default: 20)
    roll?: number        // clockwise rotation in degrees (default: 0)
    width?: number       // canvas width in pixels (default: 800)
    height?: number      // canvas height in pixels (default: 600)
}
```

## `Book3DRenderer`

用于交互式使用的持久渲染器。svg加载一次；呼叫 `render()` 反复 使用不同的角度而不需要每次重新加载纹理。

```ts
import {Book3DRenderer} from 'bookcover-3d-web'

// Create once
const renderer = new Book3DRenderer(800, 600)

// Load SVGs and build geometry (do this when the cover changes)
await renderer.load({front: frontSvg, back: backSvg, spine: spineSvg}, 'paperback')

// Render at any angle — fast, no texture reload
renderer.render(-30, 20)   // azimuth, elevation

// Export the current frame
const png = await renderer.to_png()

// Free GPU resources when done
renderer.destroy()
```

### 完整的API

```ts
const renderer = new Book3DRenderer(width?, height?)

// Load cover face SVGs and build 3D geometry
await renderer.load(svgs: BookFaces, cover_type?: CoverType, depth_mm?: number)

// Render at camera angles (all in degrees)
renderer.render(azimuth?, elevation?, zoom?, roll?, light_az?, light_el?, ambient?, exposure?)

// Resize without recreating WebGL context
renderer.resize(width, height)

// Get projected width/height ratio at default viewing angle
renderer.get_projected_aspect(): number

// Composite onto a background photo
await renderer.composite_photo(background: ImageBitmap, options?: PhotoCompositeOptions)

// Export current frame
await renderer.snapshot(): Promise<ImageBitmap>
await renderer.to_png(): Promise<Uint8Array>

// Free GPU resources
renderer.destroy()
```

## 照片合成

`composite_photo` 以一定的角度渲染书籍，并在a上进行合成 背景图像，带有由光线方向派生的阴影。它返回一个 `ImageBitmap` 在背景的原生分辨率。

![Example photo](https://npmcn.com/package/bookcover-3d-web/README_mockup.webp)

图库介绍了一组背景照片 `BACKGROUNDS` （仅限元数据） jpg本身并没有捆绑在npm包中；他们住在回购区 [资产树](https://github.com/gracious-tech/bookcover/tree/main/assets/3d/backgrounds) 供您与其他静态资产一起托管)。每个条目都有一个 `id` (识别 加载哪个图像)和预先调整的相机/照明选项，使书看起来 在那个场景里很自然。对象直接传递背景条目 `options` 论点-它 扩展 `PhotoCompositeOptions`.

```ts
import {Book3DRenderer, BACKGROUNDS} from 'bookcover-3d-web'
import type {Background} from 'bookcover-3d-web'

// Find the background you want
const bg: Background = BACKGROUNDS.find(b => b.id === 'coffee_table')!

// Load the image however you serve your assets
const img = await fetch(`/assets/3d/backgrounds/${bg.id}.jpg`)
const blob = await img.blob()
const bitmap = await createImageBitmap(blob)

// Render the book, then composite — pass the background entry as options
await renderer.load({front: frontSvg, back: backSvg, spine: spineSvg})
const result = await renderer.composite_photo(bitmap, bg)

// result is an ImageBitmap at the background's native resolution
```

可用的背景id： `table_with_book`， `wood`， `coffee_table`， `table_with_laptop`， `table_side`.

您还可以通过传递一个plain来合成您自己的图像 `PhotoCompositeOptions` 对象（所有字段都是可选的-默认情况下给出一个平面开销透视图）：

```ts
interface PhotoCompositeOptions {
    azimuth?: number      // horizontal camera angle in degrees (default: -15)
    elevation?: number    // vertical camera angle in degrees (default: 35)
    zoom?: number
    roll?: number         // clockwise rotation in degrees (default: 0)
    book_scale?: number   // book width as fraction of background width (default: 0.55)
    offset_x?: number     // position offset as fraction of background width (0 = centred)
    offset_y?: number     // position offset as fraction of background height (0 = centred)
    light_az?: number     // light horizontal angle in degrees
    light_el?: number     // light vertical angle in degrees
    ambient?: number      // ambient light level 0–1
}
```

## 常见问题

### bookcover-3d-web 是什么？

通过提供书籍封面设计，创建书籍的3D图像。部分 封套 一代系统。

### 如何安装 bookcover-3d-web？

在项目目录运行 npm install bookcover-3d-web，或使用 pnpm add / yarn add / bun add。

### bookcover-3d-web 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### bookcover-3d-web 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### bookcover-3d-web 可以商用吗？

bookcover-3d-web 使用 MIT-0 许可。声明的许可为 MIT-0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### bookcover-3d-web 还在维护吗？

最新版本 0\.24\.0 发布于 2026/11/03（今天）；至今共发布 28 个版本，其中过去 12 个月发布了 28 个；首次发布于 2026/07/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。