Mapray-JS 场景文件(JSON)格式详解

概述

Mapray-JS 是一个用于构建3D地理空间应用的JavaScript库，其场景文件采用JSON格式定义，用于描述3D场景中的各种元素和属性。本文将详细解析Mapray-JS场景文件的结构和各个组成部分。

场景文件基本结构

Mapray-JS场景文件的核心结构包含两个主要部分：

{
  "model_register": {},
  "entity_list": []
}

• model_register: 用于注册可重用的3D模型资源
• entity_list: 包含场景中所有实体的列表

模型注册(model_register)

模型注册部分允许预先定义可重用的3D模型，这些模型可以在多个实体中引用。每个模型定义包含：

{
  "link": "模型资源URL",
  "offset_transform": {
    "translate": [0, 0, 0],
    "heading": 0,
    "tilt": 0,
    "roll": 0,
    "scale": [1, 1, 1]
  }
}

• link: 指定模型资源的URL路径
• offset_transform: 定义模型的初始变换参数

实体类型(Entities)

Mapray-JS支持多种类型的实体，每种类型都有其特定的属性和配置。

1. 模型实体(Model)

用于在场景中放置3D模型：

{
  "type": "model",
  "transform": {
    "position": [经度, 纬度, 高度],
    "heading": 0,
    "tilt": 0,
    "roll": 0,
    "scale": [1, 1, 1]
  },
  "ref_model": "模型ID",
  "index": 0
}

2. 标记线(Markerline)

用于绘制连接多个地理点的线条：

{
  "type": "markerline",
  "points": [[经度,纬度,高度], ...],
  "line_width": 1,
  "color": [1, 1, 1],
  "opacity": 1
}

3. 路径(Path)

类似于标记线，但支持更复杂的路径定义：

{
  "type": "path",
  "points": {
    "positions": [[经度,纬度,高度], ...],
    "lengths": [数值数组]
  },
  "line_width": 1,
  "color": [1, 1, 1],
  "opacity": 1,
  "lower_length": 0,
  "upper_length": 0
}

4. 文本(Text)

在场景中添加文本标注：

{
  "type": "text",
  "entries": [
    {
      "text": "文本内容",
      "position": [经度, 纬度, 高度],
      "font_style": "normal",
      "font_weight": "normal",
      "font_size": 16,
      "font_family": "sans-serif",
      "color": [1, 1, 1]
    }
  ]
}

5. 多边形(Polygon)

用于绘制多边形区域：

{
  "type": "polygon",
  "boundaries": [
    {
      "type": "outer",
      "points": [[经度,纬度,高度], ...]
    }
  ],
  "extruded_height": 0.0,
  "color": [1, 1, 1],
  "opacity": 1
}

6. 图钉(Pin)

用于在地图上添加标记点：

{
  "type": "pin",
  "entries": [
    {
      "type": "icon",
      "position": [经度, 纬度, 高度],
      "size": [30, 30],
      "bg_color": [0.35, 0.61, 0.81],
      "maki_id": "图标ID"
    }
  ]
}

7. 图像图标(ImageIcon)

使用自定义图像作为图标：

{
  "type": "imageicon",
  "entries": [
    {
      "image_src": "图片URL",
      "position": [经度, 纬度, 高度],
      "size": [30, 30],
      "origin": [0.5, 0.5]
    }
  ]
}

通用属性

所有实体类型都支持以下通用属性：

• id: 实体的唯一标识符(可选)
• altitude_mode: 高度模式("absolute"、"relative"或"clamp")
• visibility: 控制实体是否可见(布尔值)

数据类型定义

Mapray-JS场景文件中使用了几种特定的数据类型：

1. GEO-POINT: [经度, 纬度, 高度]的三元素数组
2. GEO-POINTS: 多个GEO-POINT组成的数组
3. PARAM-VEC2/VEC3: 2D/3D向量
4. PARAM-SCALE3: 3D缩放参数，可以是单个数值或向量
5. PARAM-SIZE2: 2D尺寸参数，可以是单个数值或向量

最佳实践

1. 模型重用：尽可能在model_register中注册模型，然后在多个实体中引用
2. 性能优化：对于大量相似实体，考虑使用instancing技术
3. 坐标精度：注意经纬度坐标的精度，避免不必要的精度损失
4. 资源管理：合理规划模型和纹理资源的大小和数量

总结

Mapray-JS的场景文件格式提供了灵活而强大的方式来描述3D地理空间场景。通过理解各种实体类型和它们的属性，开发者可以创建丰富多样的3D地理应用。本文详细介绍了场景文件的结构和各种实体类型的配置选项，为使用Mapray-JS进行开发提供了全面的参考。