3p 中文文档教程

Question

3p: Progressive Triangle Streams

渐进式三角形流是 Hugues Hoppe 的渐进式网格的一个实现，稍作修改有利于通过视觉保真度快速解码。 格式灵活，不同的编解码器可以选择不同的顶点分割策略。 该模块记录渐进式三角流并实现二进制和 JSON 格式的参考编解码器。 这种文件格式的目的是提供一种基本的容器格式，用于试验在网格上执行边缘折叠的不同策略，并提供一种处理渐进式网格数据的通用语言。

Why use 3p?

与索引面列表等标准网格表示相比，渐进式网格有两个优势：

1. They are typically much smaller. In a binary 3P file, the topology data of the mesh uses 1/4 as much space as in a binary indexed triangle mesh and up to 1/10 as much space as an ASCII encoded equivalent.
2. They can be loaded incrementally. It is possible to process a truncated 3P file and recover an approximate geometry immediately. This decreases the amount of time spent waiting for geometry to load.

与 PLY 文件格式一样，3P 文件可以指定任意顶点和面数据。 3P 也是一种无损编码，因此顶点位置等属性不会在中间表示中被截断。 3P 可以与 gzip 等标准 HTTP 压缩方案结合使用，以进一步减小大小。

Other implementations

Reference Codec API

这些参考编解码器可通过 npm 安装：

npm install 3p

安装后，它们可以被要求并用作 CommonJS 模块。

注意 参考编解码器未优化。

Encoder

JSON

require('3p/encode-json')(vertexCount, cells[, vertexAttributes, cellAttributes, vertexTypes, cellTypes])

将三角网格压缩成 JSON 格式的渐进三角形流。

• cells is a list of triangles, each encoded as a list of 3 vertex indices
• vertexAttributes is an optional array of vertex attributes
• cellAttributes is an optional array of per-face attributes

返回 一个 3PJ 编码的网格对象

Binary

require('3p/encode-binary')(vertexCount, cells[, vertexAttributes, cellAttributes, vertexTypes, cellTypes])

与上面相同的接口，除了返回一个存储二进制 3PB 文件的 node.js Buffer 对象。

Decoder

JSON

require('3p/decode-json')(json)

解码 JSON 格式的 3PJ 对象。

• json is a plain old JavaScript object storing the parsed 3PJ data

返回 表示具有以下属性的网格的对象：

• cells is an array storing the faces of the mesh
• vertexAttributes is an array of vertex attributes
• cellAttributes is an array of cell attributes

Binary

require('3p/decode-binary')(buffer)

与上面相同，除了采用二进制 3PB 文件而不是 JSON。

JSON and binary conversion

require('3p/json-to-binary')(json)

将 JSON 3PJ 文件转换为二进制 3PB 缓冲区

• json is a 3PJ javascript object

返回 表示二进制 3PB 文件的 Buffer

require('3p/binary-to-json')(buffer)

将二进制 3PB 文件转换为 JSON 3PJ 对象

• buffer is a Buffer encoding a 3PB object

< strong>返回 JSON 3PJ 对象

Format description

渐进三角形流将 3D 三角网格编码为一系列顶点分割操作。 渐进三角形流可以具有任意数量的顶点和/或面属性，并且可以被截断以生成初始几何形状的近似值。 渐进三角形流支持两种不同的格式：用于调试的参考 JSON 格式和二进制格式。 这些格式存储等效信息。

JSON format (.3PJ)

出于调试目的，3P 支持 JSON 格式。 渐进三角形流的 JSON 格式包含与上述相同的数据。 每个 3P JSON 对象都有 3 个字段，包含以下数据：

• The file header, storing:
  • version - a string representing the version of the 3P file in semver format
  • vertexCount - the number of vertices in the stream
  • cellCount - the number of cells in the stream
  • vertexAttributeTypes - an array of types for each vertex attribute
  • cellAttributeTypes - an array of types for each cell attribute
• An initial triangulated mesh, with 4 arrays:
  • cells - an array of 3 tuples of integers representing the vertex indices for each triangle
  • vertexAttributes - an array of arrays of vertex attributes
  • cellAttributes - an array of arrays of cell attributes
• An array of vertex split operations, each having the following properties:
  • baseVertex - the vertex to split
  • attributes - attributes for newly created vertex
  • left - index of left vertex in 1-ring around base vertex
  • leftOrientation - orientation of left face
  • leftAttributes - attributes for left face
  • right - index of right face
  • rightOrientation - orientation of right face
  • rightAttributes - attributes for right face

每个类型声明应包含以下数据：

• name which is an ascii string storing the name of the type
• count which is the size of the type value
• type a string encoding the type of the attribute

type 的可能值如下：

• uint8 an unsigned 8 bit integer
• uint16 an unsigned 16 bit integer
• uint32 an unsigned 32 bit integer
• int8
• int16
• int32
• float32
• float64

JSON 格式的渐进三角形流应该使用文件扩展名 .3PJ

Binary format (.3PB)

• Network byte order
• Prefer .3PB file extension

struct S3PBFile {
  uint8[4]           "3PB\n"
  S3PBHeader         header
  S3PBComplex        initialComplex
  S3PBVertexSplit[]  vertexSplits
}

struct S3PBHeader {
  uint32             splitOffset
  uint32             majorVersion
  uint32             minorVersion
  uint32             patchVersion
  uint32             vertexCount
  uint32             cellCount
  uint32             vertexAttributeCount
  uint32             cellAttributeCount
  S3PBAttribute[]    vertexAttributeTypes
  S3PBAttribute[]    cellAttributeTypes
}

struct S3PBAttribute {
  uint32             count
  S3PBAttributeType  type
  uint32             nameLength
  char[]             name
}

enum S3PBAttributeType: uint32 {
  uint8:      0
  uint16:     1
  uint32:     2
  int8:       3
  int16:      4
  int32:      5
  float32:    6
  float64:    7
}

struct S3PBComplex {
  uint32             initialVertexCount
  uint32             initialCellCount
  VertexAttribute[]  vertexAttributes
  uint32[3][]        cells
  CellAttribute[]    cellAttributes
}

struct S3PBVertexSplit {
  uint32             baseVertex
  uint8              left
  uint8              right
  VertexAttribute    attributes
  CellAttribute      leftAttributes
  CellAttribute      rightAttributes
}

Notes

• Manifold vertices must be stored in initial complex, non-manifold vertices and their neighbors can't be split
• In S3PBVertexSplit, the upper bit of left and right stores the orientation of the vertex
• The lower 7 bits of left and right are an index into the neighbors of s
• splitOffset is the start of the vertex split section in bytes
• Attribute names are stored as ASCII text
• Encoders must not collapse edges incident to non-manifold or boundary vertices
• Vertices with more than 15 neighbors must not be split
• Encoders should prioritize edge collapses with minimal visual impact on images
• Binary decoders should gracefully handle truncated input
• Encoders may not preserve the index of each vertex. Encoding/decoding may permute the order of cells/vertices in the mesh.
• Encoding must preserve topology and all attributes
• Codecs may collapse vertices in any order subject to the implementation
• If a decoder recieves more vertices or cells than is specified in the header, then it should terminate
• cellCount and vertexCount should describe the total number of vertices in the stream. If more vertices in the stream are encountered, the decoder may choose to continue processing additional splits
• For each vertex split, the baseVertex must refer to a previous vertex in the stream

Benchmarks and comparisons

大小以字节为单位

Mesh	JSON	3p	3p + gzip
Stanford bunny	110361	33190	27531

References

TODO

License

版权所有 2014 Mikola Lysenko。 麻省理工学院执照