p5.js 加载 3D 模型（loadModel）

德育处主任

发布于 2026-02-20 08:06:59

1160

点赞 + 关注 + 收藏 = 学会了

什么是 loadModel？

loadModel() 是 p5.js 中用于加载 3D 模型的核心函数，它能将 OBJ 或 STL 格式的 3D 模型文件转换为 p5.js 可处理的 p5.Geometry 对象，之后可以通过 model() 函数在画布上显示。

基础语法结构

loadModel(path, [options])
// 或（旧版语法，功能相同）
loadModel(path, [normalize], [successCallback], [failureCallback])

path：模型文件的位置，支持两种路径形式：
- 本地路径：如 'assets/model.obj'（推荐将模型放在项目的 assets 文件夹中）
- 网络 URL：如 'https://example.com/model.stl'（受浏览器跨域限制，本地测试可能失败）

注意： 路径错误会导致加载失败，可通过失败回调函数排查。

可选参数：options（配置对象，推荐使用）

这是最灵活的参数形式，通过一个对象配置所有加载选项，支持以下属性：

属性名	类型	作用	默认值
normalize	布尔值	若为 true，自动缩放模型至适合画布大小（避免模型过大 / 过小）	false
successCallback	函数	模型加载成功后执行的函数（参数为加载完成的 p5.Geometry 对象）	无
failureCallback	函数	模型加载失败后执行的函数（参数为错误信息对象）	无
flipU	布尔值	翻转纹理的 U 坐标（解决纹理左右颠倒问题）	false
flipV	布尔值	翻转纹理的 V 坐标（解决纹理上下颠倒问题）	false
fileType	字符串	强制指定文件类型（.obj 或 .stl），当路径不含扩展名时使用	自动从路径推断

可选参数：normalize（单独缩放控制，旧版语法）
- 类型：布尔值
- 作用：等同于 options.normalize，控制是否自动缩放模型
- 使用场景：不需要其他配置时，可简化为 loadModel(path, true)
可选参数：successCallback 和 failureCallback（回调函数，旧版语法）
- 类型：函数
- 作用：分别对应 options.successCallback 和 options.failureCallback
- 使用场景：仅需要处理加载结果，不需要其他配置时使用
返回值：p5.Geometry 对象（包含模型的顶点、面、法向量等数据）
必须在 preload() 中调用：因为模型加载是异步操作，preload() 会等待所有加载完成后再执行 setup()，避免使用未加载的模型导致错误。

基础用法

在使用 loadModel() 之前，需要准备一个模型文件。

练手的话，可以用我这个模型。

在你的项目根目录中创建一个 assets 文件夹。
在 assets 里创建一个 cube.obj 文件。注意后缀是 .obj。
将下面这段代码放在 cube.obj 里保存好。

# 带底面的四棱锥模型
# 顶点坐标 (v x y z)
v  40.0  0.0  40.0   # 底面右上角
v -40.0  0.0  40.0   # 底面左上角
v -40.0  0.0 -40.0   # 底面左下角
v  40.0  0.0 -40.0   # 底面右下角
v  0.0  3.0  0.0   # 顶点

# 纹理坐标 (vt u v)
vt 1.0 1.0
vt 0.0 1.0
vt 0.0 0.0
vt 1.0 0.0
vt 0.5 0.0

# 法向量 (vn x y z)
vn 0.0 -1.0 0.0    # 底面法向量（向下）
vn 0.0 0.5 0.5     # 前面法向量
vn -0.5 0.5 0.0    # 左面法向量
vn 0.0 0.5 -0.5    # 后面法向量
vn 0.5 0.5 0.0     # 右面法向量

# 面定义（顶点/纹理/法向量）
f 1/1/1 2/2/1 3/3/1 4/4/1  # 底面
f 1/1/2 2/2/2 5/5/2        # 前面
f 2/1/3 3/2/3 5/5/3        # 左面
f 3/1/4 4/2/4 5/5/4        # 后面
f 4/1/5 1/2/5 5/5/5        # 右面

加载并显示模型

let myModel; // 存储模型对象

// 预加载：在程序开始前完成加载
function preload() {
  // 加载模型（路径改为你的模型文件位置）
  myModel = loadModel('assets/cube.obj'); 
}

function setup() {
  createCanvas(800, 600, WEBGL); // 创建3D画布（必须用WEBGL渲染模式）
}

function draw() {
  background(220);
  
  // 3D变换：让模型旋转，更易观察
  rotateX(frameCount * 0.01);
  rotateY(frameCount * 0.01);
  
  // 显示模型
  model(myModel);
}

运行代码可以看到一个会动的平面出现在画布里。

参数与回调函数

带加载回调（适合处理加载状态）

let myModel;
let loadStatus = "加载中...";

function preload() {
  // 路径 + 成功回调 + 失败回调
  loadModel(
    'assets/cube.obj', 
    (model) => { // 成功回调：模型加载完成后执行
      myModel = model;
      loadStatus = "加载成功！";
    }, 
    (error) => { // 失败回调：加载出错时执行
      loadStatus = "加载失败：" + error.message;
    }
  );
}

function setup() {
  createCanvas(400, 400, WEBGL);
}

function draw() {
  background(0);
  fill(255);
  // 显示加载状态（2D文字需用screenX/screenY转换坐标）
  push();
  translate(-width/2 + 20, -height/2 + 20);
  text(loadStatus, 0, 0); // 左上角显示状态
  pop();
  
  if (myModel) { // 模型加载完成后才显示
    rotateX(frameCount * 0.01);
    rotateY(frameCount * 0.01);
    model(myModel);
  }
}

通过回调函数实时反馈加载状态，避免因加载失败导致程序崩溃。

自动适配画布大小（normalize 参数）

let myModel;

function preload() {
  // 第二个参数设为true：自动缩放模型以适应画布
  myModel = loadModel('assets/cube.obj', true); 
}

function setup() {
  createCanvas(400, 400, WEBGL);
}

function draw() {
  background(240);
  orbitControl(); // 允许鼠标拖拽旋转模型
  model(myModel);
}

当模型过大或过小时，normalize: true 会自动缩放模型，避免超出画布或过小看不清。

以上就是本文的全部内容啦，想了解更多 P5.js 用法欢迎关注《P5.js中文教程》。

点赞 + 关注 + 收藏 = 学会了

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2026-02-20，如有侵权请联系 cloudcommunity@tencent.com 删除

对象