XGRIDS文档
  • 简体中文
  • English
  • 繁體中文
  • 日本語
  • Deutsch
  • Español
  • Italiano
  • Français
  • Русский
  • Polski
  • Nederlands
  • 简体中文
  • English
  • 繁體中文
  • 日本語
  • Deutsch
  • Español
  • Italiano
  • Français
  • Русский
  • Polski
  • Nederlands
  • 灵视 P 系列

    • 灵视 P1

      • 产品概述
      • 设备基本操作
      • 使用 LCC Scan App
      • 维护及保养
      • 常见问题
  • 灵光 K 系列

    • 灵光 K1

      • 产品概述
      • 设备基本操作
      • 设备激活与连接
      • 设备采集
      • 获取绝对坐标点云数据
      • 地图融合
      • 典型场景路线规划建议
      • 注意事项
      • 常见问题
    • 灵光 K2

      • 产品概述
      • 设备基本操作
      • 设备激活与连接
      • 设备采集
      • 获取绝对坐标点云数据
      • 地图融合
      • 典型场景路线规划建议
      • 注意事项
      • 常见问题
  • 灵光 L 系列

    • 灵光 L2 Pro

      • 产品概述
      • 设备基本操作
      • 设备激活与连接
      • 设备采集
      • 获取绝对坐标点云数据
      • 实时测量功能
      • 附录
      • 常见问题
    • 灵光 L3

      • 产品概述
      • 设备基本功能
      • 设备激活与连接
      • 设备采集
      • 获取绝对坐标点云数据操作流程
      • 附录
  • 配件

    • 补光灯

      • 安装指导
      • 基本操作
      • 常见问题
  • Lixel Studio

    • 版权
    • 安装与激活
    • 界面说明
    • 文件
    • 工程处理
    • 工具
    • 平面绘制
    • 行业应用
    • 设置
    • 设备感知
    • 常见问题 / FAQ
  • Lixel CyberColor

    • LCC Studio

      • 入门
      • 版本与更新
      • 下载与安装
      • 界面概览与导航
      • 重建前工作
      • 模型重建
      • 单模型重建
      • 地图融合
      • 空地融合
      • 航拍重建
      • 我的模型
      • 其他功能
      • 设置与账号
      • 转换工具
      • 视频重建
      • 常见问题 / FAQ
    • LCC Scene Editor

      • 版本与更新
      • 账号与登录
      • 产品概览与主页
      • 编辑器界面介绍
      • 三种场景漫游快捷操作
      • 文件
      • 设置
      • 编辑操作
      • 窗口
      • 视图工具栏
      • 资产与属性
      • 左侧工具栏
      • 视点
      • 跳转点
      • 天空盒
      • 标注
      • 测量
      • 场景漫游
      • 场景报告
      • 智能户型图(3D Layout)
      • 小地图
      • 预览模式(Viewer)
      • 帮助
      • 常见问题 / FAQ
      • 出生点
    • LCC Model Editor

      • 版本与更新
      • 新手指引
      • 概览与界面
      • 文件操作
      • 选择器
      • 编辑操作
      • 测量
      • 调色
      • 资产管理
      • 设置与帮助
      • 常见问题 / FAQ
    • 采集指南

      • 概述
      • 采集设备总览
      • 通用采集原则
      • 室内场景采集
      • 室外场景采集
      • 大场景采集(地图融合)
      • 空地融合采集
      • 物体采集
      • 人物采集
      • 视频重建采集
      • 高清补拍
      • 控制点(灵视 P1)
      • 常见问题与排查
    • LCC Studio Linux

      • 产品概要说明
      • 基本架构说明书
      • 安装部署说明书
      • 容器启动参数说明书
      • CodeMeter离线授权部署说明书
      • API指令集说明书
      • 附录-开发者数据说明书
      • 附录-错误码列表
      • 单机多卡集群部署QuickStart
    • 使用技巧

      • 多个大型 3DGS 模型融合工作流
    • 历史版本
  • Plugin & SDK

    • Unreal

      • 介绍
      • 快速入门 - Windows
      • 快速入门 - Linux
      • 快速入门 - Quest3
      • 版本与授权
      • 渲染
      • Tiled 光栅化(实验性)
      • 画面调节
      • 法线与光照
      • 场景编辑
      • 性能参数说明
      • 性能优化指南
      • 第三方与引擎插件集成
      • 代理网格
      • 加载动画
      • 碰撞
      • 寻路系统支持
      • 单层水支持
      • 本地化
      • 常见问题
      • 故障排查
      • 日志与诊断
      • 联系我们
      • 最佳实践

        • 用 LixelStudio 网格为 3DGS 重打光
      • API 参考

        • ALCCActorBase
        • ULCCComponentBase
        • ULCCComponent
        • ULCC2Component
        • SOG / SPZ / PLY Actors
        • ALCC2ProxyMesh
        • ALCCClippingVolume
        • ALCCSectionPlane
        • ALCCLoadVolume
        • ULCCUtilLibrary
        • Enums
        • Structs
      • 更新日志

        • v3.4.0
        • v3.3.1
        • v3.0.0
        • v2.2.1
        • v1.0.0
        • v0.9.0
        • v0.8.0
        • v0.7.1
        • v0.6.1
        • v0.5.2
        • v0.4.1
        • v0.4.0
        • v0.3.0
        • v0.0.5
        • v0.0.4
        • v0.0.3
        • v0.0.2
        • v0.0.1
    • Unity

      • Unity SDK 简介
      • 技术特性
      • 开发环境要求
      • PC 快速开发入门指南
      • 工程设置优化指南
      • Pico 4 Ultra 开发指南
      • Pico 4 Ultra PC 串流指南
      • Quest 3 开发指南
      • Quest 3 PC 串流指南
      • OpenXR 开发指南
      • Pico 4 Ultra 企业串流指南
      • 术语表
      • 常见问题
      • 联系我们
      • 功能开发指南

        • 多场景混合渲染开发指南
        • 阴影接收开发指南
        • 实时光照开发指南
        • 多相机渲染开发指南
        • 高清图像渲染开发指南
        • LCC 与 LCC2 数据格式兼容开发指南
        • 加载特效开发指南
        • Mip 渲染模式切换开发指南
        • 边角点吸附开发指南
        • 投影贴花开发指南
        • 视频流投影开发指南
        • 高亮显示开发指南
        • 实时裁剪开发指南
        • 调色开发指南
        • 获取场景 Mesh 数据开发指南
        • 编辑器模式开发指南
        • 渲染性能参数设置指南
        • 应用与数据协同打包开发指南
        • 碰撞系统开发指南
        • macOS 开发权限问题操作指南
        • iOS 设备编译打包开发指南
      • API 参考

        • LCCManager
        • Renderer
        • 数据类型
      • 更新日志

        • v2.3.0
        • v2.2.10
        • v2.2.0
        • v2.1.19
        • v2.0.14
    • X-Brain

      • 产品概述
      • 硬件接口
      • 快速开始
      • 核心概念
      • 集成指南
      • API 参考
      • 数据类型
      • ROS2 桥接
      • 示例程序
      • 部署与网络
      • 排障与 FAQ
      • 版本与发布
    • Web

      • 介绍
      • 渲染性能优化指南
      • 显卡配置
      • 常见开发问题
      • API参考

        • LCCRender::clearIndexDB
        • LCCRender::dispose
        • LCCRender::load
        • LCCRender::setCamera
        • LCCRender::unload
        • LCCRender::update
        • LCCObject::checkRenderNextFrame
        • LCCObject::clearRenderNextFrame
        • LCCObject::ecef2Prj
        • LCCObject::getBounds
        • LCCObject::getEnvInstancedMesh
        • LCCObject::getInstancedMesh
        • LCCObject::getLodInfos
        • LCCObject::getOriginPosition
        • LCCObject::getProjectionCoordinateSystemInfos
        • LCCObject::hasCollision
        • LCCObject::hasEnvironment
        • LCCObject::hasShcoef
        • LCCObject::intersectsCapsule
        • LCCObject::intersectsRayExt
        • LCCObject::intersectsRayFromOriginExt
        • LCCObject::intersectsSphere
        • LCCObject::lowerToBottom
        • LCCObject::prj2Ecef
        • LCCObject::raiseToTop
        • LCCObject::raycast
        • LCCObject::raycastFromOrigin
        • LCCObject::setAlpha
        • LCCObject::setClipBox
        • LCCObject::setClipPlane
        • LCCObject::setEndLod
        • LCCObject::setLodAutoLevelUp
        • LCCObject::setMaxDistance
        • LCCObject::setMaxNodeSplats
        • LCCObject::setMaxSplats
        • LCCObject::setOriginPosition
        • LCCObject::setPointsColor
        • LCCObject::setRenderState
        • LCCObject::setRotation
        • LCCObject::setScale
        • LCCObject::setSemantic
        • LCCObject::setSemanticColor
        • LCCObject::setSmooth
        • LCCObject::setStartLod
        • LCCObject::setTranslation
        • LCCObject::setVisible
        • LCCObject::togglePointsDisplayMode
        • LCCObject::useEnvironment
        • LCCObject::useShcoef
      • 更新日志

        • v0.6.3
        • v0.6.2
        • v0.6.1
        • v0.6.0
        • v0.5.5
        • v0.5.4
        • v0.5.3
        • v0.5.2
        • v0.5.1
        • v0.5.0
        • v0.4.1
        • v0.4.0
        • v0.3.1
        • v0.3.0
        • v0.2.0
    • Lixel OpenAPI

      • 概述
      • 连接与鉴权
      • 消息模型与编解码
      • 接口清单
      • 实时数据
      • 项目文件访问
      • 错误码
      • Python

        • 快速开始
        • 客户端封装与工具
        • 常见问题
      • C++

        • 快速开始
        • 客户端与示例
        • 常见问题

LCCManager:核心管理器

LCC Unity SDK 的核心管理器,负责管理所有 Renderer 实例、相机、全局渲染状态,以及编辑操作(裁切 / 高亮 / 调色)、贴花投影、吸附、交互查询(射线 / 碰撞)等。整个场景中应仅存在一个 LCCManager 实例。

命名空间LCCCore
父类MonoBehaviour

LCCManager 没有公开属性,所有功能通过方法调用。方法按用途分为以下几组:

  • 初始化与配置
  • 运行时渲染控制
  • 光照与阴影
  • 相机管理
  • 裁切 / 高亮 / 调色
  • 贴花投影
  • 吸附
  • 射线检测与碰撞查询
  • 特效
  • 实例查询

初始化与配置

以下方法用于在加载数据前完成平台、渲染模式、容量等前置配置。多数方法必须在任何 Renderer.Load() 之前调用。

SetPlatformType

public void SetPlatformType(PlatformType _type)

设置 SDK 目标运行平台,影响内部渲染策略与资源分配。

参数类型说明
_typePlatformType目标平台,取值见 PlatformType

说明:

  • 必须在任何 GetRender() 调用之前执行。

调用示例:

lccManager.SetPlatformType(PlatformType.PC);

SwitchRenderPass

public void SwitchRenderPass(ActiveRenderMode _mode)

设置全局渲染架构模式。MultiRender 使用共享 GPU Buffer,可同时渲染最多 255 个 Renderer;SingleRender 由 SDK 根据数据量自动选择渲染路径。

参数类型说明
_modeActiveRenderMode渲染模式,取值见 ActiveRenderMode

说明:

  • 必须在任何 Renderer.Load() 之前调用。
  • 仅 PC / Mac 平台有效;移动端 / VR 平台会自动采用适配策略,调用本方法会被拒绝。
  • MultiRender 模式不支持 HTTP 数据源,HTTP 数据请使用 SingleRender。
  • 一旦有任意 Renderer 完成 Load(),模式即被锁定,不能再切换。

调用示例:

lccManager.SwitchRenderPass(ActiveRenderMode.MultiRender);

GetRender(重载 1:绑定 Transform)

// 返回值:Renderer,失败返回 null
public Renderer GetRender(Transform _transform)

创建一个新的渲染实例并绑定到指定 Transform。创建后需调用 Renderer.Load() 加载数据。

参数类型说明
_transformTransform渲染实例挂载的 Transform

说明:

  • 需先调用 SetPlatformType() 与 SetMainCamera()。
  • MultiRender 模式下最多支持 255 个 Renderer。

调用示例:

var go = new GameObject("LCCScene");
var renderer = lccManager.GetRender(go.transform);
renderer.Load(filePath, null, () => Debug.Log("Loaded"));

GetRender(重载 2:自动创建 GameObject)

// 返回值:Renderer,失败返回 null
public Renderer GetRender(out GameObject gameObject)

自动创建名为 LCCRenderer 的 GameObject 并将渲染实例绑定到其 Transform 上。

参数类型说明
gameObjectout GameObject输出自动创建的 GameObject,失败时为 null

调用示例:

var renderer = lccManager.GetRender(out GameObject go);
renderer.Load(filePath, null, () => Debug.Log("Loaded"));

SetMaxBufferSplat

public void SetMaxBufferSplat(int _count)

设置 GPU Buffer 最大容量(Splat 数量)。一次性分配,不可动态修改。

参数类型说明
_countint最大 Splat 数量,单位:万(传入值 × 10000 = 实际数量)

说明:

  • 必须在任何 Renderer.Load() 之前调用,且需先调用 SetPlatformType()。
  • 容量越大显存占用越高,按需设置。
  • 平台上限:PC / Mac / PCVR 4500 万,Android / iOS 600 万,VR(Pico / Quest / PicoSwan / AVP / OpenXR)200 万。
  • 默认值:PC / Mac 3000 万,Android / iOS 300 万,VR 100 万。

调用示例:

lccManager.SetMaxBufferSplat(3000); // 3000 万点

SetFullRenderSplat

public void SetFullRenderSplat(int _count)

设置 PC / Mac 全量渲染的上限阈值。当数据量小于此值时走全量渲染路径,否则走分块渲染路径。

参数类型说明
_countint全量渲染上限,单位:万,取值范围 [100, 4500]

说明:

  • 仅 PC / Mac / PCVR 平台支持。
  • 必须在任何 Renderer.Load() 之前调用,且需先调用 SetPlatformType()。

调用示例:

lccManager.SetFullRenderSplat(2500); // 2500 万点

SetMaxRenderSplats

public void SetMaxRenderSplats(int _count)

设置运行时每帧最大渲染 Splat 数量。可在 Load() 之后动态调用。

参数类型说明
_countint运行时最大渲染 Splat 数量,单位:万

说明:

  • 可在运行时动态调整。
  • 不能超过 SetMaxBufferSplat() 设置的容量上限,超出会自动钳制。
  • 全量渲染模式下调用无效。

调用示例:

lccManager.SetMaxRenderSplats(2500); // 2500 万点

GetLoadRatio

// 返回值:float,[0,1] 当前数据加载进度
public float GetLoadRatio()

查询当前画面数据的加载进度。

说明:

  • 全量渲染模式下恒返回 1.0。
  • 分块渲染模式下返回当前视角下已加载完成节点的比例,数值随相机移动实时变化,并非单调递增的总体进度。

调用示例:

float ratio = lccManager.GetLoadRatio();
progressBar.value = ratio;

SetSelectionMode

public void SetSelectionMode(SelectionMode mode)

设置节点筛选策略。

参数类型说明
modeSelectionMode筛选策略,取值见 SelectionMode

说明:

  • Auto(默认):根据场景整体包围盒自动决策,当场景最大维度超过约 380 米时自动升级到 Large。
  • Normal:适用于中小场景。
  • Large:适用于超大场景(1000 米以上)。
  • 切换模式立即生效。

调用示例:

lccManager.SetSelectionMode(SelectionMode.Auto);

运行时渲染控制

以下方法可在运行时动态调用,用于调整渲染精度、显示效果与渲染开关。

SetDetailLevel

public void SetDetailLevel(float sse)

设置渲染精度等级。值越大渲染越精细、性能消耗越高。

参数类型说明
ssefloat精度等级,范围 [1, 100],超出自动钳制

说明:

  • 采用对数映射:低值区间变化敏感,高值区间变化平缓。
  • 运行时可动态调整。
  • 仅在 Normal 筛选模式下生效。

调用示例:

lccManager.SetDetailLevel(50f); // 中等精度

SetStartLod

public void SetStartLod(int lod)

设置 LOD 展开起点(0-based)。0 表示最精细,数字越大层级越粗。

参数类型说明
lodintLOD 起始层级,范围 [0, 10],超出自动钳制

说明:

  • 实际生效上限受数据总层级数限制。

调用示例:

lccManager.SetStartLod(0);

SetAutoFov

public void SetAutoFov(bool _auto)

设置是否自动管理渲染 FOV。开启(默认)后 SDK 在首帧锁定一个像素焦距基准,此后每帧按当前视口高度反解垂直 FOV 并写回 Camera.fieldOfView;关闭后 fieldOfView 交由外部(SetFOV() 或直接改相机)掌握。

参数类型说明
_autobool是否自动 FOV

说明:

  • 默认开启。
  • 开启时会持续改写主相机 Camera.fieldOfView,此时调用 SetFOV() 会被忽略。
  • 关闭后需手动调用 SetFOV() 设置参数。

调用示例:

lccManager.SetAutoFov(true);

SetFOV

public void SetFOV(int _width, int _height, float _verticalFov, float _aspect)

手动设置垂直 FOV(度)。直接改写主相机的 Camera.fieldOfView,使 Inspector 中的 FOV 与渲染实际使用的 FOV 一致。_width / _height / _aspect 为历史签名保留参数,实际投影以主相机自身视口为准(需要异于相机的尺寸 / FOV 离屏出图请用 SetRecordMode())。

参数类型说明
_widthint像素宽度
_heightint像素高度
_verticalFovfloat垂直 FOV(度)
_aspectfloat宽高比

说明:

  • 需先调用 SetAutoFov(false),否则自动 FOV 每帧反解会覆盖手动值。
  • 垂直 FOV 钳制到 [1, 179] 度。
  • VR / PCVR 平台、录制中、正交相机下调用会被拒绝(告警并返回)。

调用示例:

lccManager.SetFOV(1920, 1080, 60f, 1.778f);

SetRenderEnable

public void SetRenderEnable(Renderer _renderer, bool _isEnable)

在运行时控制指定 Renderer 的渲染开关。禁用后不参与遍历和绘制。

参数类型说明
_rendererRenderer目标渲染实例
_isEnablebool是否启用渲染

调用示例:

lccManager.SetRenderEnable(renderer, false); // 隐藏

SetEnvironment

public void SetEnvironment(Renderer _renderer, bool _isRender)

控制指定 Renderer 的环境数据渲染。环境数据为低精度背景点云,用于填充远景。

参数类型说明
_rendererRenderer目标渲染实例
_isRenderbool是否渲染环境数据

说明:

  • 数据需包含环境节点。

调用示例:

lccManager.SetEnvironment(renderer, true);

SetZDepth

public void SetZDepth(bool zwrite)

开关 Z 深度写入,同时调整渲染队列。

参数类型说明
zwritebool是否开启 Z 深度写入

调用示例:

lccManager.SetZDepth(true);

SetAlpha

public void SetAlpha(float alpha)

设置全局透明度。

参数类型说明
alphafloat全局透明度,范围 [0, 1],超出自动钳制

调用示例:

lccManager.SetAlpha(0.8f);

SetLightIntensity

public void SetLightIntensity(float intensity)

设置全局光照强度。

参数类型说明
intensityfloat光照强度,范围 [0, 1],超出自动钳制

调用示例:

lccManager.SetLightIntensity(0.7f);

SetLowPassFilter

public void SetLowPassFilter(float _filter)

设置全局低通滤波强度,用于抑制高频锯齿 / 噪点。

参数类型说明
_filterfloat低通滤波强度,范围 [0, 1],超出自动钳制

调用示例:

lccManager.SetLowPassFilter(0.3f);

SetLockFPS

public void SetLockFPS(bool _isLock)

开关帧率锁定(静态 / 动态帧率切换)。

参数类型说明
_isLockbool是否锁定帧率

调用示例:

lccManager.SetLockFPS(true);

SetRenderLayer

public void SetRenderLayer(int _layer)

设置 LCC 渲染使用的 Unity Layer,用于相机 CullingMask 控制可见性。

参数类型说明
_layerintUnity 渲染层级,范围 [0, 31]

说明:

  • 运行时可动态调整。

调用示例:

lccManager.SetRenderLayer(8); // 使用 Layer 8

SetForceRefresh

public void SetForceRefresh()

强制刷新渲染。清除内部相机信息缓存,使下一帧重新计算视锥、LOD 等参数。适用于外部修改相机参数后需要立即生效的场景。

调用示例:

lccManager.SetForceRefresh();

SetMipMode

public void SetMipMode(MipMode _mipMode)

切换 Mip 渲染模式。Mip 模式使用 mipmap 采样(默认),Non_Mip 模式禁用 mipmap。

参数类型说明
_mipModeMipMode目标模式,取值见 MipMode

说明:

  • 若当前模式与传入模式相同则直接返回。
  • 切换立即生效。

调用示例:

lccManager.SetMipMode(MipMode.Non_Mip);

SetGraphicsAPI

public void SetGraphicsAPI(GraphicsDeviceType type)

设置图形 API 类型。DX11 模式下启用 HDR。

参数类型说明
typeGraphicsDeviceType图形 API 类型(Unity 内置枚举)

调用示例:

lccManager.SetGraphicsAPI(GraphicsDeviceType.Direct3D11);

SetDebugMode

public void SetDebugMode(bool debug)

开关调试模式。

参数类型说明
debugbool是否开启调试模式

说明:

  • 仅 PC / Mac 平台支持。

调用示例:

lccManager.SetDebugMode(true);

SetEditorMode

public void SetEditorMode(bool _isEditor)

开关编辑器模式。

参数类型说明
_isEditorbool是否开启编辑器模式

说明:

  • 仅 PC / Mac 平台支持。

调用示例:

lccManager.SetEditorMode(true);

SetAECMode

public void SetAECMode(bool _aec)

开关 AEC(建筑 / 工程 / 施工)模式。

参数类型说明
_aecbool是否开启 AEC 模式

说明:

  • 仅 PC / Mac 平台支持。

调用示例:

lccManager.SetAECMode(true);

SetSemantic

// 返回值:bool,false=参数无效
public bool SetSemantic(bool enable, Vector4[] color = null)

开关语义渲染模式。启用时可传入颜色数组定义各语义类别的显示颜色。

参数类型说明
enablebool是否启用语义渲染
colorVector4[]语义颜色数组,长度必须为 100,否则返回 false;传 null 使用默认颜色

调用示例:

Vector4[] colors = new Vector4[100];
colors[0] = new Vector4(1, 0, 0, 1); // 类别 0 = 红色
lccManager.SetSemantic(true, colors);

SwitchRenderMode

public void SwitchRenderMode(RenderMode mode, Texture2D tex = null)

切换点云渲染与 3DGS 渲染模式。点云模式下可提供高程色带纹理。

参数类型说明
modeRenderMode渲染模式,取值见 RenderMode
texTexture2D高程色带图(可选)

说明:

  • 仅 PC / Mac 平台支持。

调用示例:

lccManager.SwitchRenderMode(RenderMode.PointCloud, elevationTex);

SetRecordMode

public void SetRecordMode(bool isRecord, Vector2 renderSize, float verticalFov)

设置录制模式。录制模式下使用固定分辨率和 FOV 渲染,适用于高清视频录制。

参数类型说明
isRecordbool是否录制模式
renderSizeVector2录制分辨率
verticalFovfloat垂直 FOV(度)

说明:

  • 仅 PC / Mac 平台支持。
  • 录制模式下相机焦距固定,不随 Camera 组件变化。
  • 结束录制后调用 SetRecordMode(false, ...) 恢复。

调用示例:

lccManager.SetRecordMode(true, new Vector2(3840, 2160), 60f);

SetVRPerformance

public void SetVRPerformance(bool _enabled)

设置 VR 高性能排序模式。true 使用 GPU 基数排序(GpuSorter),false 回退到 CPU / BitonicSorter 兜底。

参数类型说明
_enabledbool是否启用 GPU 高性能排序

说明:

  • 仅对 VR 头显(Pico / Quest / PicoSwan / OpenXR)的排序路径生效,默认开启。
  • 无 compute 设备(如 Mali)时由排序上游自动回退到 CPU,不受此开关影响。

调用示例:

lccManager.SetVRPerformance(true);

光照与阴影

以下方法用于控制 3DGS 表面的阴影接收与自定义点光源。阴影相关方法需在 LCC 场景加载完成后调用。

SetShadowReceive

public void SetShadowReceive(bool enable)

开关点云阴影接收功能。开启后场景中 Mesh 物体的阴影可以投射到 3DGS 点云表面上。

参数类型说明
enablebool是否接收阴影

说明:

  • 默认关闭。
  • 需要场景中有投射阴影的 Mesh 物体和 Directional Light 光源。

调用示例:

lccManager.SetShadowReceive(true);

SetShadowColor

public void SetShadowColor(Color color)

设置阴影区域的颜色。

参数类型说明
colorColor阴影颜色(RGBA)

说明:

  • 默认值 (0.3, 0.3, 0.3, 1)。
  • 需先开启 SetShadowReceive(true)。

调用示例:

lccManager.SetShadowColor(new Color(0.3f, 0.3f, 0.3f, 1f));

SetShadowStrength

public void SetShadowStrength(float strength)

设置阴影强度。0 为无阴影,1 为最强阴影。

参数类型说明
strengthfloat阴影强度,范围 [0, 1],超出自动钳制

说明:

  • 默认值 1.0。
  • 需先开启 SetShadowReceive(true)。

调用示例:

lccManager.SetShadowStrength(0.8f);

SetLights

// 返回值:int,0=成功,-1=超出最大数量限制
public int SetLights(List<PointLightData> lights)

设置自定义点光源列表。传入 null 或空列表可关闭自定义光照。

参数类型说明
lightsList<PointLightData>点光源列表,字段见 PointLightData

说明:

  • PointLightData.lightType:0 为点光源(忽略 direction / spotAngle),1 为聚光灯(需设置 direction / spotAngle)。
  • 传入 null 或空列表关闭自定义光照。

调用示例:

using Unity.Mathematics; // float3

var lights = new List<PointLightData>();
lights.Add(new PointLightData {
    position = new float3(0, 5, 0),
    lightType = 0,              // 0=点光源, 1=聚光灯
    color = new float3(1, 1, 1),
    intensity = 2f,
    range = 10f
});
lccManager.SetLights(lights);

相机管理

SetMainCamera

public void SetMainCamera(Camera _cam)

设置主渲染相机。LCC 使用此相机进行视锥裁剪、LOD 选择、排序等操作。

参数类型说明
_camCamera主渲染相机,传 null 可清除

说明:

  • 必须在 Renderer.Load() 之前设置。
  • 仅 PC / Mac 平台支持。

调用示例:

lccManager.SetMainCamera(Camera.main);

AddCamera

public void AddCamera(Camera _cam)

添加一个副相机。副相机参与渲染但不影响 LOD 选择。

参数类型说明
_camCamera副相机

说明:

  • 仅 PC / Mac 平台支持。
  • 不能将主相机添加为副相机。

调用示例:

lccManager.AddCamera(secondCamera);

RemoveCamera

public void RemoveCamera(Camera _cam)

移除一个已添加的副相机。

参数类型说明
_camCamera要移除的副相机

说明:

  • 仅 PC / Mac 平台支持。

调用示例:

lccManager.RemoveCamera(secondCamera);

裁切 / 高亮 / 调色

裁切、高亮、调色三类编辑操作,均支持通过 2D 纹理、3D 几何体或两者混合定义作用区域。相关数据结构见 Data2D、Data3D、DataMix、ToneMix。

SetClip(平面裁切)

// 返回值:int,0=成功
public int SetClip(Vector3 planePoint, Vector3 planeNormal, bool inside = true)

使用无限平面裁切点云,保留法线方向一侧或反侧的点。

参数类型说明
planePointVector3平面上一点
planeNormalVector3平面法线
insidebooltrue 保留法线方向侧

说明:

  • 与其他裁切模式互斥。

调用示例:

lccManager.SetClip(Vector3.zero, Vector3.up, true); // 保留地面以上

SetClip(2D 纹理裁切)

// 返回值:int,0=成功,1=列表为空,2=超出最大数量
public int SetClip(List<Data2D> _2Ds)

使用 2D 投影纹理蒙版裁切点云。

参数类型说明
_2DsList<Data2D>2D 纹理选区列表

调用示例:

var clips = new List<Data2D>();
clips.Add(new Data2D {
    texture = maskTex,
    mv = modelViewMatrix,
    mvp = mvpMatrix,
    mode = SelectMode.normal
});
lccManager.SetClip(clips);

SetClip(3D 几何体裁切)

// 返回值:int,0=成功,1=列表为空,2=超出最大数量,3=有效几何体为 0
public int SetClip(List<Data3D> _3Ds)

使用 3D 几何体裁切点云,支持布尔运算组合多个几何体。

参数类型说明
_3DsList<Data3D>3D 几何体列表

说明:

  • 至少需要一个 operation == normal 的几何体。

调用示例:

var clips = new List<Data3D>();
clips.Add(new Data3D {
    type = ShapeType.box,
    invMat = boxInverseMatrix,
    operation = OperationMode.normal,
    mode = SelectMode.normal
});
lccManager.SetClip(clips);

SetClip(混合模式裁切)

// 返回值:int,0=成功,1=列表为空,2=超出最大数量
public int SetClip(List<DataMix> mix)

同时使用 2D 纹理和 3D 几何体混合定义裁切区域。每个条目通过 editType 指定类型。

参数类型说明
mixList<DataMix>混合选区列表(2D + 3D)

调用示例:

var mix = new List<DataMix>();
mix.Add(new DataMix {
    editType = EditType.Edit3D,
    type = ShapeType.box,
    invMat = matrix,
    operation = OperationMode.normal,
    mode = SelectMode.normal
});
lccManager.SetClip(mix);

QuitClipMode

public void QuitClipMode()

退出裁切模式,恢复完整点云显示。

调用示例:

lccManager.QuitClipMode();

SetHighlight(2D 纹理高亮)

// 返回值:int,0=成功,1=列表为空,2=超出最大数量
public int SetHighlight(List<Data2D> _2Ds)

使用 2D 投影纹理蒙版对点云进行高亮显示,高亮区域外的点云变暗。

参数类型说明
_2DsList<Data2D>2D 纹理选区列表

说明:

  • 与 3D 高亮和混合高亮互斥。

调用示例:

var highlights = new List<Data2D>();
highlights.Add(new Data2D {
    texture = maskTex,
    mv = modelViewMatrix,
    mvp = mvpMatrix,
    mode = SelectMode.normal
});
lccManager.SetHighlight(highlights);

SetHighlight(3D 几何体高亮)

// 返回值:int,0=成功,1=列表为空,2=超出最大数量,3=有效几何体为 0
public int SetHighlight(List<Data3D> _3Ds)

使用 3D 几何体定义高亮区域,支持布尔运算组合。

参数类型说明
_3DsList<Data3D>3D 几何体列表

说明:

  • 至少需要一个 operation == normal 的几何体。

调用示例:

var highlights = new List<Data3D>();
highlights.Add(new Data3D {
    type = ShapeType.box,
    invMat = boxInverseMatrix,
    operation = OperationMode.normal,
    mode = SelectMode.normal
});
lccManager.SetHighlight(highlights);

SetHighlight(混合模式高亮)

// 返回值:int,0=成功,1=列表为空,2=超出最大数量
public int SetHighlight(List<DataMix> mix)

同时使用 2D 纹理和 3D 几何体混合定义高亮区域。

参数类型说明
mixList<DataMix>混合选区列表

调用示例:

var mix = new List<DataMix>();
mix.Add(new DataMix {
    editType = EditType.Edit3D,
    type = ShapeType.box,
    invMat = matrix,
    operation = OperationMode.normal,
    mode = SelectMode.normal
});
lccManager.SetHighlight(mix);

QuitHighlightMode

public void QuitHighlightMode()

退出高亮模式,恢复点云正常显示。

调用示例:

lccManager.QuitHighlightMode();

SetTone

// 返回值:int,0=成功,1=列表为空,2=超出最大数量
public int SetTone(List<ToneMix> mix)

对选定区域进行调色处理,支持亮度、饱和度、对比度调整和 LUT 滤镜。可通过 2D 纹理或 3D 几何体定义调色区域。

参数类型说明
mixList<ToneMix>调色混合列表

说明:

  • brightness / saturation / contrast 默认值为 1.0。
  • lutid 为 LUT 滤镜索引,0 表示不使用。

调用示例:

var tones = new List<ToneMix>();
tones.Add(new ToneMix {
    editType = EditType.Edit3D,
    type = ShapeType.box,
    invMat = boxMatrix,
    operation = OperationMode.normal,
    mode = SelectMode.normal,
    brightness = 1.2f,
    saturation = 1.0f,
    contrast = 1.1f,
    lutid = 0
});
lccManager.SetTone(tones);

QuitToneMode

public void QuitToneMode()

退出调色模式,恢复点云原始色彩。

调用示例:

lccManager.QuitToneMode();

贴花投影

贴花投影可将一张纹理沿投影仪方向投射到 3DGS 表面。贴花是世界固定的全局状态,对所有相机一致。典型流程为:开启贴花 → 设置纹理 → 设置投影仪位姿。以下方法仅 PC / Mac 平台支持。

SetDecalEnabled

public void SetDecalEnabled(bool enable)

开关贴花投影。需另外调用 SetDecalTexture() 与 SetDecalProjection() 设置内容与投影仪位姿。

参数类型说明
enablebool是否开启贴花投影

说明:

  • 关闭时不会清空已缓存的纹理 / 参数。

调用示例:

lccManager.SetDecalEnabled(true);
lccManager.SetDecalTexture(decalTex);
lccManager.SetDecalProjection(projectorPos, projectorRot, 60f, 1.778f, 0.1f, 20f);

SetDecalTexture

public void SetDecalTexture(Texture2D tex)

设置贴花纹理。RGB 为颜色,A 为贴花自身遮罩,会与全局不透明度、边缘羽化相乘。

参数类型说明
texTexture2D贴花纹理,传 null 会清空引用

调用示例:

lccManager.SetDecalTexture(logoTex);

SetDecalProjection

public void SetDecalProjection(Vector3 pos, Quaternion rot, float fov, float aspect, float near, float far)

设置贴花投影仪的位姿与透视参数。投影仪沿其 forward(+Z)方向投影,视锥内的点被贴花覆盖。

参数类型说明
posVector3投影仪世界坐标
rotQuaternion投影仪朝向
fovfloat垂直 FOV(度),钳制 [1, 179]
aspectfloat宽高比,最小 1e-4
nearfloat近裁剪面,最小 1e-3
farfloat远裁剪面,最小 near + 1e-3

调用示例:

lccManager.SetDecalProjection(new Vector3(0, 10, 0), Quaternion.Euler(90, 0, 0), 60f, 1.778f, 0.1f, 20f);

SetDecalOpacity

public void SetDecalOpacity(float opacity)

设置贴花整体不透明度。

参数类型说明
opacityfloat贴花整体不透明度,范围 [0, 1],超出自动钳制

调用示例:

lccManager.SetDecalOpacity(0.8f);

SetDecalEdgeFade

public void SetDecalEdgeFade(float edgeFade)

设置贴花边缘羽化宽度。0 为硬边,值越大边缘过渡越柔和。

参数类型说明
edgeFadefloat边缘羽化宽度(UV 空间比例),范围 [0, 0.5),超出自动钳制

调用示例:

lccManager.SetDecalEdgeFade(0.1f);

SetDecalOcclusion

public void SetDecalOcclusion(bool enable)

开关贴花遮挡剔除(基于投影仪深度图),开启后被遮挡的表面不会被贴花覆盖。

参数类型说明
enablebool是否开启贴花遮挡剔除

说明:

  • 仅 PC / Mac 平台,且仅 URP 管线支持。
  • 开启前应已调用 SetDecalProjection() 设定投影仪。
  • 依赖 SetDecalOcclusionSettings() 配置的质量参数。

调用示例:

lccManager.SetDecalOcclusion(true);

SetDecalOcclusionSettings

public void SetDecalOcclusionSettings(DecalOcclusionSettings settings)

一次性设置贴花遮挡剔除的全部质量参数。字段含义见 DecalOcclusionSettings。

参数类型说明
settingsDecalOcclusionSettings遮挡剔除质量参数

说明:

  • 随时可调,参数立即生效。

调用示例:

lccManager.SetDecalOcclusionSettings(DecalOcclusionSettings.Default);
lccManager.SetDecalOcclusionSettings(new DecalOcclusionSettings {
    opacityCutoff = 0.1f,
    depthBias = 0.05f,
    footprintMaxPx = 2,
    resolution = 1024
});

吸附

吸附功能可在射线检测时自动搜索附近的边缘 / 角点进行对齐,常用于测量、标注等精确交互。以下方法仅 PC / Mac 平台支持。

SetSnapEnabled

public void SetSnapEnabled(bool enable)

开关吸附功能。启用后 RaycastWithSnap() 会自动搜索附近的边缘 / 角点进行吸附。

参数类型说明
enablebool是否启用吸附

说明:

  • 默认关闭。
  • 移动端 / VR 调用无效并输出警告。

调用示例:

lccManager.SetSnapEnabled(true);

SetSnapRadius

public void SetSnapRadius(float pixels)

设置吸附搜索半径。在此像素范围内搜索最近的边缘 / 角点。

参数类型说明
pixelsfloat吸附搜索半径(像素)

说明:

  • 默认 20 像素。
  • 值越大搜索范围越广,但可能吸附到非预期目标。

调用示例:

lccManager.SetSnapRadius(30f);

SetEdgeThreshold

public void SetEdgeThreshold(float threshold)

设置边缘检测阈值。值越小检测到的边缘越多。

参数类型说明
thresholdfloat边缘检测阈值,建议范围 [0.1, 0.8]

说明:

  • 默认 0.3。
  • 值过小会产生大量噪声边缘。

调用示例:

lccManager.SetEdgeThreshold(0.2f);

SetSnapPreviewEnabled

public void SetSnapPreviewEnabled(bool enable)

开关吸附预览功能。启用后鼠标移动时实时显示最近的吸附目标指示器。

参数类型说明
enablebool是否启用吸附预览

说明:

  • 需先调用 SetSnapEnabled(true)。
  • 预览会持续消耗 GPU 资源(每帧检测)。

调用示例:

lccManager.SetSnapPreviewEnabled(true);

UpdateSnapPreview

public void UpdateSnapPreview(Vector2 mousePos, Camera cam)

更新吸附预览状态。在鼠标移动时调用,更新预览指示器位置。

参数类型说明
mousePosVector2当前鼠标屏幕坐标
camCamera相机

说明:

  • 需先调用 SetSnapPreviewEnabled(true)。
  • 建议在 Update 中持续调用。

调用示例:

void Update()
{
    lccManager.UpdateSnapPreview(Input.mousePosition, Camera.main);
}

GetSnapPreviewState

// 返回值:SnapPreviewState
public SnapPreviewState GetSnapPreviewState()

获取当前吸附预览状态,包括是否有吸附目标、目标类型、目标屏幕位置和到鼠标的像素距离。字段见 SnapPreviewState。

说明:

  • 需先调用 SetSnapPreviewEnabled(true) 和 UpdateSnapPreview()。
  • 无目标时返回 default(SnapPreviewState)。
  • screenPos 是屏幕坐标,不是世界坐标;要拿世界坐标请用 RaycastWithSnap() 取 HitResult.hitPos。

调用示例:

var state = lccManager.GetSnapPreviewState();
if (state.hasTarget)
{
    // state.snapType: Corner / Edge
    // state.screenPos: 吸附目标屏幕坐标
    // state.distanceToMouse: 像素距离
}

射线检测与碰撞查询

射线检测用于拾取 3DGS 表面上的点,碰撞查询用于角色 / 物体与点云的物理交互。命中结果通过 HitResult 返回。

注意:

HitResult 的命中点世界坐标字段名为 hitPos(不是 position)。

Raycast(屏幕坐标)

// 返回值:bool,true=命中
public bool Raycast(Vector3 mousePos, out HitResult _finalResult)

从屏幕坐标发射射线检测点云命中。使用 SetMainCamera() 设置的主相机生成射线。

参数类型说明
mousePosVector3屏幕坐标
_finalResultout HitResult命中结果

说明:

  • 需先调用 SetMainCamera() 设置主相机。
  • 返回距离相机最近的命中点。
  • 精度受 SetRaycastDelta() 影响,最大距离由 SetMaxRaycastDistance() 控制。

调用示例:

if (lccManager.Raycast(Input.mousePosition, out HitResult hit))
{
    Debug.Log(hit.hitPos);
}

Raycast(Ray)

// 返回值:bool,true=命中
public bool Raycast(Ray _ray, out HitResult _finalResult)

使用自定义 Ray 进行射线检测,遍历所有激活的 Renderer 返回最近命中。

参数类型说明
_rayRay射线
_finalResultout HitResult命中结果

调用示例:

Ray ray = new Ray(origin, direction);
if (lccManager.Raycast(ray, out HitResult hit))
{
    Debug.Log(hit.hitPos);
}

RaycastMesh(屏幕坐标)

// 返回值:bool,true=命中
public bool RaycastMesh(Vector3 mousePos, out HitResult _finalResult, float _distance = 70.0f)

从屏幕坐标发射射线检测点云碰撞网格。使用 Collider 数据进行检测,比 Raycast() 更快但精度较低。

参数类型说明
mousePosVector3屏幕坐标
_finalResultout HitResult命中结果
_distancefloat最大检测距离,默认 70.0

说明:

  • 需要数据包含 Collider 节点,且需先调用 Renderer.SetColliderEnable(true)。

调用示例:

if (lccManager.RaycastMesh(Input.mousePosition, out HitResult hit))
{
    Debug.Log(hit.hitPos);
}

RaycastMesh(Ray + Bounds)

// 返回值:bool,true=命中
public bool RaycastMesh(Ray ray, out HitResult result, out Bounds hitBounds, float maxDist = 70.0f)

使用自定义 Ray 进行碰撞网格检测,同时返回命中节点的包围盒信息。

参数类型说明
rayRay射线
resultout HitResult命中结果
hitBoundsout Bounds命中节点的包围盒
maxDistfloat最大检测距离,默认 70.0

说明:

  • 需要数据包含 Collider 节点。

调用示例:

Ray ray = Camera.main.ScreenPointToRay(Input.mousePosition);
if (lccManager.RaycastMesh(ray, out HitResult hit, out Bounds bounds))
{
    Debug.Log(bounds.center);
}

RaycastWithSnap

// 返回值:bool,true=命中
public bool RaycastWithSnap(Vector2 screenPos, Camera cam, out HitResult result)

带吸附功能的射线检测。先进行普通射线检测,再在命中点附近搜索边缘 / 角点进行吸附。

参数类型说明
screenPosVector2屏幕坐标
camCamera相机
resultout HitResult命中结果(含吸附信息)

说明:

  • 需先调用 SetSnapEnabled(true)。
  • 仅 PC / Mac 平台支持,移动端 / VR 不可用。
  • 吸附优先级:Corner > Edge > None。
  • HitResult.snapType 为吸附类型,HitResult.hitPos 为吸附后的世界坐标,HitResult.originalHitPos 为吸附前的原始命中点。

调用示例:

if (lccManager.RaycastWithSnap(mousePos, cam, out HitResult hit))
{
    // hit.snapType: Corner / Edge / None
    // hit.hitPos: 吸附后的世界坐标
    // hit.originalHitPos: 吸附前的原始命中点
}

SetRaycastDelta

public void SetRaycastDelta(float delta)

设置射线检测的精度参数。值越小精度越高但性能消耗越大。

参数类型说明
deltafloat射线检测精度,范围 [0.1, 10.0],超出自动钳制

说明:

  • 默认值 0.1。
  • 影响所有 Raycast() 方法的检测精度。

调用示例:

lccManager.SetRaycastDelta(0.5f);

SetMaxRaycastDistance

public void SetMaxRaycastDistance(float _distance)

设置 Raycast() 方法的最大检测距离。

参数类型说明
_distancefloat最大射线检测距离,范围 [10, 10000],超出自动钳制

说明:

  • 影响 Raycast(Vector3) / Raycast(Ray) 两个重载;不影响 RaycastMesh()(其有独立的距离入参)。

调用示例:

lccManager.SetMaxRaycastDistance(500f);

IntersectsSphere

// 返回值:bool,true=相交
public bool IntersectsSphere(Sphere sphere)

// 返回值:bool,true=相交
public bool IntersectsSphere(Sphere sphere, out Vector3 delta)

检测球体与点云碰撞体是否相交。第二个重载额外返回穿透向量,可用于物理推出。

参数类型说明
sphereSphere球体
deltaout Vector3穿透向量(推出方向和距离)

说明:

  • 需要数据包含 Collider 节点,且需先调用 Renderer.SetColliderEnable(true)。
  • 遍历所有激活的 Renderer。

调用示例:

var sphere = new Sphere(transform.position, 0.5f);
if (lccManager.IntersectsSphere(sphere, out Vector3 delta))
{
    transform.position += delta;
}

IntersectsCapsule

// 返回值:bool,true=相交
public bool IntersectsCapsule(Capsule capsule)

// 返回值:bool,true=相交
public bool IntersectsCapsule(Capsule capsule, out Vector3 delta)

检测胶囊体与点云碰撞体是否相交,常用于角色控制器碰撞检测。第二个重载返回穿透向量。

参数类型说明
capsuleCapsule胶囊体
deltaout Vector3穿透向量

说明:

  • 需要数据包含 Collider 节点,且需先调用 Renderer.SetColliderEnable(true)。

调用示例:

var capsule = new Capsule(footPos, headPos, 0.3f);
if (lccManager.IntersectsCapsule(capsule, out Vector3 delta))
{
    characterController.Move(delta);
}

特效

TriggerVFX

public void TriggerVFX(Vector3 vfxOriginW, int vfxid = 0)

在指定世界坐标触发特效,特效从该坐标点向外扩展蔓延。

参数类型说明
vfxOriginWVector3特效的世界坐标原点
vfxidint特效效果 ID,默认 0

说明:

  • 需在 LCC 场景加载完成后调用。

调用示例:

lccManager.TriggerVFX(hitPoint, 0);

实例查询

GetAllRenderers

// 返回值:List<Renderer>,所有已注册的 Renderer 实例副本
public List<Renderer> GetAllRenderers()

获取当前所有已注册的 Renderer 实例列表(返回副本)。

调用示例:

var renderers = lccManager.GetAllRenderers();
foreach (var r in renderers) { /* ... */ }