STP在线查看器

1.产品介绍

STP在线查看器主要用于在线查看和预览STP（STEP)格式的文件，这些文件是三维图形数据，基于ASCII格式，并遵循ISO 10303-21标准的正文编码的交换结构。STP在线查看器的核心功能是将STP文件转换为适合在线展示的格式，从而使用户能够在网页浏览器中直接查看和交互这些三维图形数据。

让复杂的3D数据变得触手可及

在机加工或相关行业中，STP/STEP文件是不可或缺的一部分。这些文件不仅包含了复杂的三维模型数据，更是您项目成功的关键。但如何高效、准确地解析和预览这些文件，一直是许多工程师和技术人员面临的挑战。

现在，我们为您带来了stpViewer——一款功能强大、操作简便的3D模型解析与预览软件。它将帮助您轻松应对各种3D文件处理需求，让您的工作更加高效、流畅。

核心优势

1. 高效解析：stpViewer采用先进的解析技术，能够迅速加载并解析STP/STEP文件，确保您能够快速获取模型数据。
2. 直观预览：通过tiny-viewer.js SDK，您可以在软件中直接预览3D模型，无需额外安装插件或软件。
3. 丰富的视图控制：支持旋转、缩放、平移等基本视图控制，让您能够全方位地查看模型细节。
4. 高级设置选项：提供光照、视角、剖切、模型选择等高级设置，满足您对于模型展示的各种需求。
5. 完善的REST API：系统提供了丰富完善的REST API接口，方便将stpViewer的功能集成到自己的项目中，实现无缝对接。

为何选择stpViewer?

• 针对性强：专为机加工或相关行业的用户设计，深入了解您的需求，提供针对性的解决方案。
• 易于操作：简洁明了的设计，让您无需复杂的培训即可上手操作。
• 性价比高：提供高性价比的产品方案，让您在获得高质量服务的同时，也能享受到实惠的价格。

2.stpViewer服务部署

2.1 部署准备

2.1.1 资源介绍

stpViewer 服务的所有必需文件资源打包在一个名为 stpViewer_service.zip 的压缩包中。解压后，您将获得以下文件列表：

序号	文件名称	类型	备注
1	tiny-3dconvert-server1.1.tar	文件	Tiny_3DConvert Server Docker镜像压缩包
2	tiny-fileimport-latest.tar	文件	Tiny_FileImport 最新 Docker镜像压缩包
3	docker-compose.yml	文件	Docker Compose 配置示例文件
4	init.sql	文件	数据库初始化脚本
5	tinydata	文件夹	数据配置文件夹，存放各服务所需数据文件的路径配置
6	nsdtlock	文件	Linux命令行工具，用于验证LICENSE并解锁服务
7	tiny-viewer.js	文件	3D模型预览JavaScript版SDK

2.1.2 平台概述

stpViewer 是一个轻量级的3D服务平台，采用 Docker 容器化技术进行部署。整个运行环境由以下4个子服务组成：

• postgres: 数据库服务，用于存储3D数据及相关业务数据。
• minIo: 高性能对象存储服务，用于存储3D源文件及其关联数据。
• tiny-3dconvert-server: 服务端API接口提供者。
• tiny-fileimport: 文件导入服务。

2.1.3 服务镜像构建

在开始部署前，请确保已安装并配置好 Docker 和 Docker Compose 环境。首先创建一个新的文件夹并将解压后的资源 1-6 复制到该文件夹中。对于未提供的 postgres 和 minIo 镜像，可直接从官方拉取；而 tiny-3dconvert-server 和 tiny-fileimport 可通过导入镜像文件构建，操作步骤如下：

1. 拉取官方镜像：

   # 拉取postgres镜像
   docker pull postgres:13.1-alpine
   
   # 拉取minIo镜像
   docker pull minio/minio
   

2. 导入自定义镜像：

   # 导入tiny-3dconvert-server镜像
   docker load -i tiny-3dconvert-server1.1.tar
   
   # 导入tiny-fileimport镜像
   docker load -i tiny-fileimport-latest.tar
   

​ 确认镜像构建成功，请运行 docker images 命令，若显示包含以下四个镜像，则表明镜像构建成功。

2.1.4 获取license

在部署tiny-3dconvert服务之前，您需要获取有效的license。在资源文件中有一个nsdtlock的命令行工具，该工具负责验证授权和解锁等工作。具体做法是需要将该工具运行起来，运行3个命令，如下：

chmod +x nsdtlock
nohup ./nsdtlock > nsdtlock.log 2>&1 &
iptables -I INPUT -p tcp --dport 5555 -j ACCEPT

运行完成之后，该命令行会产生一个machine mac的码，使用如下命令查看码：

tail -f 200 nsdtlock.log

将machine mac码复制，发给tiny-server的客服人员，他会给你一个LICENSE，然后将LICENSE配置到docker-compose.yaml/tiny-3dconvert-server/environment/LICENSE_CODE，并且在MAC_IP配置项中配置docker容器宿主机的ip地址。

另外nsdtlock这个命令行工具产生的进程不要杀掉，请保持运行直到服务已经完成启动、并且通过了授权验证，或者干脆让此进程一直运行。

下一步是基于这些镜像构建容器和服务，详情请参阅 第2章 “部署”部分的内容。

2.2 部署

2.2.1 配置详解

​ docker-compose.yaml 文件中提供了四个容器的配置示例，大部分配置无需更改，但请注意标记需要修改的部分。具体配置示例如下：

version: "3.5"
services:
  tiny-postgres:
    image: "postgres:13.1-alpine"
    restart: always
    environment:
      POSTGRES_DB: tiny_3dconvert
      POSTGRES_USER: tiny3dconvert
      POSTGRES_PASSWORD: tiny3dconvert
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /etc/timezone:/etc/timezone
      - ./tinydata/postgres-data:/var/lib/postgresql/data/
    ports:
      - "7432:5432"
  
  tiny-minio:
    image: "minio/minio"
    command: server /data --console-address ":9002"
    restart: always
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /etc/timezone:/etc/timezone
      - ./tinydata/minio-data:/data
    ports:
      - "9900:9000"
      - "9002:9002"
  
  tiny-fileimport-service:
    image: registry.cn-hangzhou.aliyuncs.com/nsdt/tiny-fileimport 
    container_name: tiny-fileimport-service
    restart: always
    privileged: true
    ulimits:
      core: 0
    volumes:
      - ./tinydata/tiny-fileimport-service/.env:/fileimport-service/.env
      - /etc/localtime:/etc/localtime:ro
    environment:
      TZ: "Asia/Shanghai"
      DEBUG: "fileimport-service:*"
      # 根据实际情况进行配置
      PG_CONNECTION_STRING: "postgres://tiny3dconvert:tiny3dconvert@ip:7432/tiny_3dconvert"
      WAIT_HOSTS: postgres:7432
      # 根据实际情况进行配置
      S3_ENDPOINT: "http://ip:9900"
      S3_ACCESS_KEY: "minioadmin"
      S3_SECRET_KEY: "minioadmin"
      S3_BUCKET: "speckle-server"
      #根据实际情况进行配置
      LICENSE_CODE: "xxxLICENSE_CODE"
      # 根据实际情况进行配置
      TINY_SERVER_URL: "http://ip:5500"

  tiny-3dconvert-server:
    container_name: tiny-3dconvert-server
    image: nsdt/tiny-3dconvert-server:1.1
    ports:
      - "5500:3000"
    environment:
      TZ: "Asia/Shanghai"
      NODE_ENV: "production"
      PORT: 3000
      BIND_ADDRESS: "0.0.0.0"
      CANONICAL_URL: "http://127.0.0.1:3000"
      # 根据实际情况进行配置
      S3_ENDPOINT: "http://ip:9900"
      S3_ACCESS_KEY: "minioadmin"
      S3_SECRET_KEY: "minioadmin"
      S3_BUCKET: "speckle-server"
      S3_CREATE_BUCKET: true
      FILE_SIZE_LIMIT_MB: 500
      
      # 根据实际情况进行配置
      POSTGRES_URL: "postgres://tiny3dconvert:tiny3dconvert@ip:7432/tiny_3dconvert"
      POSTGRES_MAX_CONNECTIONS_SERVER: 10
      # 根据实际情况进行配置
      LICENSE_CODE: ""
      MAC_IP: "172.16.0.245"

      WAIT_HOSTS: tiny-postgres:7432, minio:9900

    restart: always
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./tinydata/tinylogs:/app/logs

在配置过程中，请根据实际环境需求，正确设置与 postgres、minIo、tiny-fileimport-service 和 tiny-3dconvert-server 相关的环境变量和连接信息。

2.2.2 数据库容器构建与初始化

1. 构建数据库容器

   不修改配置的情况下，可以使用以下命令构建 PostgreSQL 容器：

   docker-compose up -d tiny-postgres
   

2. 初始化数据库表

   连接至数据库（初始数据库名：tiny_3dconvert，用户名：tiny3dconvert，密码：tiny3dconvert），执行 init.sql 初始化脚本以完成数据库表结构初始化。如下：

2.2.3 minIo 容器构建

构建 minIo 容器同样简便，只需运行以下命令：

docker-compose up -d tiny-minio

2.2.4 tiny-fileimport 与 tiny-3dconvert-server 容器构建

tiny-fileimport-service 和 tiny-3dconvert-server 服务分别依赖于数据库、minIo 服务，并需要配置正确的环境变量。请确保在 docker-compose.yaml 中相应服务下的配置项，如 PG_CONNECTION_STRING、POSTGRES_URL、S3_ENDPOINT、TINY_SERVER_URL 等均设置准确无误。

构建两个服务的命令分别为：

docker-compose up -d tiny-fileimport-service
docker-compose up -d tiny-3dconvert-server

使用docker logs tiny-3dconvert-server -f 命令查看服务日志，看到如下界面说明LICENSE验证成功、整个服务构成功。。

3. 服务端API

3.1 文件上传接口

接口名称：文件上传

接口URL：${BASE_URL}/api/file/:fileType/:streamId

HTTP 方法：POST

描述：该接口用于上传指定类型的3D文件至指定的工作空间（streamId）。

请求参数：

• URL Path Parameters：
  • fileType （string，必填）：文件类型，例如 "stp"、"step" 等3D文件格式。
  • streamId （string，必填）：目标工作空间ID，例如 3fe0ed8b68。
• Request Headers：
  • Content-Type （string，必填）：设置为 multipart/form-data，用于上传文件内容。
• Request Body：
  • file （file，必填）：待上传的3D文件，以 multipart/form-data 格式提交。

响应参数：

• Status Code：
  • 200 OK：文件上传成功，响应体包含上传结果的JSON对象。
  • 400 Bad Request：请求参数错误或文件不满足要求。
  • 401 Unauthorized：用户未授权访问该资源。
  • 5XX Server Error：服务器错误。

响应体示例（成功）：

{
    "uploadResults": [
        {
            "blobId": "037d715265",
            "fileName": "J1.STEP",
            "uploadStatus": 1,
            "fileSize": 2213080,
            "formKey": "file"
        }
    ]
}

---

3.2 查询文件信息接口

接口名称：查询文件详情

接口URL：${BASE_URL}/api/file/filecommit/:fileId

HTTP 方法：GET

描述：此接口用于查询单个文件的详细信息，包括转换状态和错误信息等。

请求参数：

• URL Path Parameters：
  • fileId （string，必填）：待查询文件的唯一标识ID（blobId）。

响应参数：

• Status Code：
  • 200 OK：查询成功，响应体包含文件详情的JSON对象。
  • 400 Bad Request：请求参数错误。
  • 5XX Server Error：服务器错误。

响应体示例（成功）：

{
    "fileId": "037d715265",
    "commitId": "2660129011",
    "referencedObject": "9b3156401e480189c443aebef6985157",
    "uploadComplete": true,
    "uploadDate": "2024-03-01T02:57:36.997Z",
    "convertedStatus": 2,
    "convertedLastUpdate": "2024-03-01T02:57:54.008Z",
    "comment": null,
    "convertedMessage": "File converted successfully"
}

---

3.3 源文件下载接口

接口名称：下载源文件

接口URL：${BASE_URL}/api/stream/:streamId/blob/:fileId

HTTP 方法：GET

描述：此接口用于下载指定文件，通过工作空间ID和文件ID获取原始文件内容。

请求参数：

• URL Path Parameters：
  • streamId （string，必填）：工作空间ID。
  • fileId （string，必填）：待下载文件的唯一标识ID（blobId）。

响应参数：

• Status Code：
  • 200 OK：文件下载成功，响应体为原始文件内容。
  • 400 Bad Request：请求参数错误。
  • 5XX Server Error：服务器错误。

---

3.4 分页查询文件信息接口

接口名称：分页查询文件列表

接口URL：${BASE_URL}/api/file/list

HTTP 方法：POST

描述：此接口用于按条件分页查询文件列表，返回每个文件的详细信息。

请求参数：

• Body Parameters：
  • streamId （string，必填）：工作空间ID。
  • startDate （string，非必填）：开始时间，格式为 YYYY-MM-DD HH:mm:ss。
  • endDate （string，非必填）：结束时间，格式同上。
  • pageNum （number，必填）：当前页码。
  • pageSize （number，必填）：每页显示的记录数。

响应参数：

• Status Code：
  • 200 OK：查询成功，响应体包含分页文件列表的JSON对象。
  • 400 Bad Request：请求参数错误。
  • 5XX Server Error：服务器错误。

响应体示例（成功）：

{
    "code": 0,
    "data": {
        "total": [
            {
                "count": "70"
            }
        ],
        "list": [
           {
                 "id": "bf49015de5",
                "streamId": "fbdb0ea035",
                "branchName": "main",
                "userId": "58743da94c",
                "fileName": "Myinhe.fbx.zip",
                "fileType": "fbx",
                "fileSize": 2532192,
                "uploadComplete": true,
                "uploadDate": "2024-03-01T03:15:24.584Z",
                "convertedStatus": 2,
                "convertedLastUpdate": "2024-03-01T03:15:37.218Z",
                "convertedMessage": "File converted successfully",
                "convertedCommitId": "11aadfbdda",
             }
        ]
    }
}

---

4. tiny-viewer.js SDK 使用指南

4.1 SDK 概述

tiny-viewer.js SDK 是3D模型查看器组件，方便开发者集成到Web应用中，实现快速加载和展示3D模型的功能。

4.2 主要功能与特性

1. 模型加载：通过指定模型资源链接或上传的blobId，加载并显示3D模型。
2. 交互控制：支持旋转、缩放、平移等基本视图控制，以及光照、视角、剖切、模型选择等高级设置。
3. 扩展性良好：支持多种3D模型格式，可根据项目需求定制拓展功能。

4.3 快速开始

• 安装：引入tiny-viewer.js SDK到项目中。
• 初始化：在页面中创建Viewer实例，并设置必要参数。
• 加载模型：使用SDK提供的方法加载3D模型。
• 事件监听：注册相关事件监听器，处理用户交互或模型加载状态变更等。

示例代码

// 引入tiny-viewer.js SDK
import TinyViewer from './src/tiny-viewer.js';

async function load3dModal() {
    const baseUrl = 'https://tinyconvert.sever.com'
    // 创建Viewer实例
    const viewer = new TinyViewer('#viewer-container', { baseUrl });
    
    // 初始化
    await viewer.init();
    // 加载模型
    const fileId = 'xxxxxxx'
    await viewer.loadObjectByFileId(fileId,{ enableCaching: false })

    // 注册事件监听器
    viewer.on('load-progress', (e) => {
      console.log('模型加载进度', e);
    });
}

load3dModal()

4.4 TinyViewer api

4.4.1 创建 TinyViewer 对象

const viewer = new TinyViewer(container: HTMLElement, params: ViewerParams);

• container: TinyViewer绑定的HTML元素

• params: ViewerParams tinyViewer配置

  interface ViewerParams {
    baseUrl: string
    showStats?: boolean
    environmentSrc?: Asset | string
      verbose: boolean
  }
  

  • baseUrl: tiny_3dconvert服务端地址，这个是必须的
  • showStats: 启用/禁用viewer画布左上角的统计窗口
  • environmentSrc: 允许用户为viewer场景定义环境纹理，形式为equirectangular HDRI
  • verbose: 在控制台中显示其他信息和警告。

在开始使用viewer之前，您需要像下面这样对其进行初始化：

await viewer.init()

该函数是异步的，因为在这一步骤中，viewer要么加载所需的资产（如您可能在params中提供的HDRI），要么生成运行时资产。

4.4.2 事件绑定 ViewerEvent

on(eventType: ViewerEvent, handler: (arg) => void)

• eventType : ViewerEvent

  enum ViewerEvent {
    ObjectClicked = 'object-clicked',
    ObjectDoubleClicked = 'object-doubleclicked',
    DownloadComplete = 'download-complete'
    LoadComplete = 'load-complete',
    LoadProgress = 'load-progress',
    LoadCancelled = 'load-cancelled',
    UnloadComplete = 'unload-complete',
    UnloadAllComplete = 'unload-all-complete',
    Busy = 'busy',
    SectionBoxChanged = 'section-box-changed'
    SectionBoxUpdated = 'section-box-updated'
  }
  

• handler: 回调函数

2.4.3 加载和卸载模型

TinyViewer通过文件id加载存储在服务端的模型

loadObject(fileId: string, {enableCaching?: boolean}): Promise<void>

• fileId: 模型对应的文件id
• enableCaching: 启用/禁用浏览器中的数据缓存。默认为true

卸载模型

unloadObject(): Promise<void>

4.4.4 相机控制

4.4.4.1 控制视角

setView(view: CanonicalView)

用于操作相机的视角

• view: CanonicalView：

  type CanonicalView =
    | 'front'
    | 'back'
    | 'up'
    | 'top'
    | 'down'
    | 'bottom'
    | 'right'
    | 'left'
    | '3d'
    | '3D'
  

4.4.4.2 透视/正交相机切换

toggleCameraProjection()

4.4.4.3 Z/Y轴向上切换

toggleZXAxisUpFixed()

4.5 选中模型对象

设置模型选中并且高亮

selectObjects(objects:[]<objectId>);

• objects： objectId集合

当用户在viewer中点击某个3d对象时，监听ObjectClicked或ObjectDoubleClicked事件的回调函数会收到SelectionEvent信息：

type SelectionEvent = {
  multiple: boolean
  event?: PointerEvent
  hits: Array<{
    guid?: string
    object: Record<string, unknown>
    point: Vector3
  }>
}

• 当没有点击对象时，则会使用 null 作为参数触发 ObjectClicked 事件

作为一个简单的例子，在单击对象时将其高亮并且聚焦：

viewer.on(ViewerEvent.ObjectClicked, (selectionInfo: SelectionEvent) => {
  if (selectionInfo) {
      // 选中对象 并且高亮对象
      viewer.selectObjects([selectionInfo.hits[0].object.id])
    // 对象聚焦
    viewer.zoom([selectionInfo.hits[0].object.id ])
  }
    else {
        //没有点击的对象。聚焦整个场景
        viewer.zoom()	
    }
})

4.6 剖切盒

tiny-viewer提供了一个可配置的剪切盒功能，可用于查看场景的部分内容。

setSectionBox(
  box?: {
    min: { x: number; y: number; z: number }
    max: { x: number; y: number; z: number }
  },
  offset?: number
)

使用即时盒子定义设置切割盒的尺寸。

• box：切割盒尺寸的盒子定义。如果未提供此参数，则切割盒将调整为整个场景大小。
• offset：用于增加/减小切割盒的可选乘数，默认为0.05。

setSectionBoxFromObjects(objectIds: string[], offset?: number)**

根据一组对象设置切割盒的尺寸。

• objectIds：我们希望调整切割盒的对象ID。切割盒的尺寸将是其组合轴对齐边界框的结果。
• offset：用于增加/减小切割盒的可选乘数，默认为0.05。

启用切割盒。

sectionBoxOn(): void

禁用切割盒。

sectionBoxOff(): void

切换切割盒的开/关状态。

toggleSectionBox(): void

4.7 光照控制

设置光照

setLightConfiguration(config: LightConfiguration): void

config: LightConfiguration：

interface LightConfiguration {
  enabled?: boolean
  castShadow?: boolean
  intensity?: number
  color?: number
  indirectLightIntensity?: number
}

interface SunLightConfiguration extends LightConfiguration {
  elevation?: number
  azimuth?: number
  radius?: number
}

• enabled：启用/禁用太阳直射光
• castShadow：启用/禁用太阳光投射阴影
• intensity：太阳光的强度
• color：太阳光的颜色（以 int 类型表示）
• indirectLightIntensity：环境光强度（IBL）的强度
• elevation：太阳球面角（以弧度为单位）
• azimuth：太阳球面方位角（以弧度为单位）
• radius：从场景包围球半径的偏移距离

系统默认配置：

export const DefaultLightConfiguration = {
  enabled: true, // 太阳阴影是否开启
  castShadow: false,
  intensity: 3, // 太阳光强度
  color: 0xffffff,
  elevation: 1.8, // 太阳高度
  azimuth: 0.75, // 太阳方位角
  radius: 0,
  indirectLightIntensity: 2,
  shadowcatcher: false,
};

5. 技术支持与答疑

目前版本部署只支持linux，如有windows或其它平台的部署需求请联系我们。

stpViewer在线查看器支持stp、step格式文件的输入，如果有其3d格式的文件的展示、3d转换等需求请联系我们。