📖 CityEngine 使用手册

版本 3.3 | 浏览器中的 CGA 城市建模引擎

1. 平台介绍

CityEngine 是一个基于浏览器的 CGA (Computer Generated Architecture) 规则引擎，支持从 OpenStreetMap 数据自动生成 3D 城市建筑模型。无需安装任何软件，即可在浏览器中完成从城市数据获取到 3D 模型生成的完整流程。

2. 快速开始

2.1 注册与登录

打开 CityEngine 主应用，点击右上角 登录 按钮。首次使用请点击 创建账户 完成注册。注册时会自动创建一个个人组织（Tenant）。

官网首页提供两个编辑器入口：Basic 编辑器（标准版）和 Visul 编辑器（可视化版），均需登录后使用。未登录点击入口会直接弹出微信扫码登录框，扫码确认后自动进入对应编辑器；首页顶部与底部的「微信扫码登录」按钮同样直接弹出二维码，底部入口登录成功后直达用户控制台。

2.2 获取地图数据

点击顶部菜单 🌍 GetMapData，在弹出的地图窗口中：

1. 搜索城市名称定位到目标区域
2. 点击 设置范围 按钮，在地图上点击两个对角点框选下载区域
3. 勾选需要下载的数据类型：建筑轮廓、道路网络
4. 勾选 从形状生成模型 以自动应用 CGA 规则
5. 点击 下载 按钮

2.3 运行 CGA 规则

下载完成后，左侧编辑器会加载默认的 CGA 规则。点击顶部 ▶ Generate 3D 按钮即可生成 3D 模型。您可以在编辑器中修改规则，实时预览效果。

2.4 选择解析引擎

顶部工具栏提供多种解析引擎选择：

引擎	说明	适用场景
CE Native	浏览器原生解析器	推荐，兼容性最佳
CGAJS	JavaScript 解析器	复杂规则，性能更好
Auto	自动选择	系统自动判断最优引擎

2.5 3D 视口与显示控制

3D 视口提供接近桌面软件的显示效果，顶部快捷开关包括：

开关	说明
天空	环境天空背景，可选 日间 / 黄昏 / 夜间 三种氛围
阴影	实时软阴影，随光源方向变化
网格	地面参考网格（细网格 + 千米级主网格），远景自动淡出
坐标轴	世界坐标轴显示

分析菜单还提供 阴影研究（模拟不同时段日照投影）等可视化分析工具。

3. CGA 规则编写

CityEngine 支持完整的 CityEngine CGA 语法。以下是常用指令示例：

// 基础建筑生成
Lot --> extrude(10) comp(f) { top: Roof | side: Facade }

Facade --> split(y) { ~3: Floor }*

Floor --> split(x) { ~2: Window | ~1: Wall }*

Roof --> roofGable(30) color("#8B4513")

Window --> primitiveCube color("#87CEEB")
Wall --> primitiveCube color("#F5F5DC")

3.1 常用操作

操作	快捷键	说明
保存	Ctrl+S	保存当前项目和 CGA 代码
生成 3D	Ctrl+Enter	运行 CGA 生成 3D 模型
撤销	Ctrl+Z	撤销编辑器修改
全屏	F11	浏览器全屏模式

3.2 代码自动补全

CGA 编辑器内置智能补全：输入函数名前几个字母即弹出候选列表，每条候选带参数签名和中文说明。用 ↑ ↓ 选择，Enter 确认插入，Esc 关闭。补全浮层始终显示在最上层，不会被编辑器边框遮挡。

完整语法参考请查看菜单 Help > CGA Reference 或访问 Esri CGA 官方文档。

4. OSM 地图数据

4.1 支持的 OSM 标签

OSM 标签	说明	引擎映射
building:levels	楼层数	建筑高度
roof:shape	屋顶形状	gable / flat / hip
building:colour	建筑颜色	Facade 颜色
height	精确高度	extrude 高度

4.2 默认规则

下载 OSM 建筑数据时，系统会自动为每个建筑项分配默认 CGA 规则（如 osm_building_global），读取 OSM 属性生成对应的 3D 模型。默认规则由平台统一维护，您也可以在检查器中随时为单个建筑更换规则。

5. 项目管理

5.1 创建与保存

点击菜单 File > Save 或按 Ctrl+S，当前 CGA 代码和场景数据会保存到您的账户中。项目支持跨设备同步。

5.2 自动保存

CGA 编辑器对文本文件（.cga 规则、.py 脚本）提供自动保存：停止输入数秒后自动落盘，编辑器失焦时也会补存一次。其他类型文件（如场景 .cej）请使用 Ctrl+S 手动保存。

5.3 工作区目录

每个项目工作区包含三个系统保留目录，请勿删除：

目录	用途
Lib/	规则库（如 ESRI.lib 示例规则）
favorites/	收藏的规则与资源
uploads/	上传的本地文件

5.4 项目分享

在控制台的 我的项目 页面中，您可以生成公开分享链接。获得链接的用户无需登录即可查看 CGA 代码和场景数据。

6. 3D 导出

CityEngine 支持以下导出格式：

格式	扩展名	状态
glTF 2.0	.gltf	已支持
glTF Binary	.glb	已支持
Wavefront OBJ	.obj	已支持

导出功能可通过控制台菜单 File > Export 或 API 调用。

7. CGA 助手（AI）

CGA 助手是平台内置的 AI 代码生成助手，用自然语言描述即可生成 CGA 规则，开箱即用，无需自行配置任何 API Key（平台统一托管密钥并自动切换）。

7.1 使用方法

1. 登录后打开主应用，点击右侧面板的 🤖 CGA 助手 标签页
2. 在输入框中描述需求，例如：生成一个现代风格的高层办公楼，玻璃幕墙，底部有裙房
3. AI 生成 CGA 规则代码后，可一键插入编辑器并运行预览

7.2 调用额度

CGA 助手按调用次数计费：每次对话消耗 1 次 CGA 调用额度。套餐内包含的免费额度用完后，可在控制台 套餐配额 页直接购买 CGA 调用包补充，即买即用。

8. 计费与订阅

CityEngine 提供多种订阅方案，注册即自动分配免费版：

方案	价格	项目数	存储	CGA 调用/月
免费版	¥0	1	100MB	0
体验版	¥30/月	5	1GB	按配置
标准版	¥100/月	50	5GB	按配置
高级版	¥300/月	300	20GB	按配置

8.1 升级与充值

控制台 套餐配额 页是计费的统一入口：

• 升级套餐：当前套餐卡片下方一键展开全部套餐选项，在线升级
• 我的余额：查看账户余额并充值（微信支付 / 支付宝）
• CGA 调用包：套餐外按量补充 AI 调用次数

9. 资源市场

CityEngine 资源市场提供多种类型的资源：

类型	说明
CGA 规则	CGA 规则源码，可直接在编辑器中使用
RPK 包	完整的 CityEngine 工程包
工程文件	CityEngine 项目模板
软件下载	辅助工具和软件
插件下载	浏览器扩展和插件

市场入口：/marketplace.html

市场页顶部另设有「精品源码包」入口，跳转至源码商店（softwarecollege.cn）购买整包 CGA 规则源码（买断下载、含商用授权），与站内单条资源的余额购买互补。

9.1 发布资源

在控制台的 发布资源 页面中，填写资源名称、描述、价格，上传文件或粘贴 CGA 源码即可发布。所有资源需经平台审核后上线。

10. 用户控制台

用户控制台是管理个人账户的入口（/console.html），菜单精简为五项：

• 套餐配额：账户总览——当前套餐（可一键升级）、CGA 调用剩余（可购买调用包）、我的余额（可充值）、配额与用量统计
• 我的项目：项目列表管理、分享链接
• 我的资源：已购买的 CGA 规则与资源
• 发布资源：向资源市场发布作品
• 账户设置：账户信息（登录名/邮箱/注册方式）、微信扫码用户可设置登录名与登录密码（设置后可免扫码登录）、修改密码

11. API 接口

11.1 认证

所有 API 请求需在 Header 中携带 Authorization: Bearer <token>。通过 POST /api/auth/login 获取 token。

11.2 常用接口

GET  /api/ping              # 健康检查
POST /api/auth/login        # 登录
POST /api/auth/register     # 注册
GET  /api/project/list      # 列出项目
POST /api/project/save      # 保存项目
GET  /api/v1/ce/plans       # 套餐列表
GET  /api/v1/ce/subscription # 当前订阅
GET  /api/v1/ce/quota       # 配额信息

12. 常见问题