JMesh explained

JMesh
Mime:	application/json
Type Code:	TEXT and BINARY
Extension:	.jmsh, .bmsh
Developer:	Qianqian Fang
Released:	^[1]
Latest Release Version:	1.0 Draft 1
Latest Release Date:	^[2]
Genre:	Data interchange
Extended From:	JSON, JData
Open:	Yes

JMesh is a JSON-based portable and extensible file format for the storage and interchange of unstructured geometric data, including discretized geometries such as triangular and tetrahedral meshes, parametric geometries such as NURBS curves and surfaces, and constructive geometries such as constructive solid geometry (CGS) of shape primitives and meshes. Built upon the JData specification, a JMesh file utilizes the JSON and Universal Binary JSON (UBJSON) constructs to serialize and encode geometric data structures, therefore, it can be directly processed by most existing JSON and UBJSON parsers. The JMesh specification defines a list of JSON-compatible constructs to encode geometric data, including N-dimensional (ND) vertices, curves, surfaces, solid elements, shape primitives, their interactions (such as CGS) and spatial relations, together with their associated properties, such as numerical values, colors, normals, materials, textures and other properties related to graphics data manipulation, 3D fabrication, computer graphics rendering and animations.

JMesh file example

The following mesh (a tetrahedral mesh of a unit cube) contains 8 3-D vertices, 12 triangular faces and 6 tetrahedral elements

The above mesh can be stored in the JMesh/JSON format asThe optional "_DataInfo_" record can contain additional metadata according to JData specification.

Instead of using dimension-specific mesh data constructs, i.e. MeshVertex3, MeshTri3, and MeshTet4, one can also replace those with the corresponding flexible mesh data containers, MeshNode, MeshSurf, and MeshElem, respectively. It is recommended to add "Dimension": 3 in the "_DataInfo_" metadata header to help parsers correctly process the numerical data in each entry.

Alternatively, according to JMesh and JData specifications, the above JSON-styled 2-D arrays can be stored as a structure using JData annotated N-D array format to add additional binary data type support, as below

For large mesh data files, record-level compression is supported via the JData specification. Just for illustration purposes, the above JMesh data can also be written aswhere the strings in "_ArrayZipData_" store the row-major serialized, Zlib-compressed and Base64 encoded binary stream of the raw binary array data in the precision specified in _ArrayType_. Record-level data compression may offer significant size reduction in storing large mesh files.

Format Overview

JMesh syntax

All JMesh files are JData specification compliant. Same as JData, it has both a text-format based on JSON serialization scheme and a binary format based on the UBJSON serialization scheme.

Nearly all supported mesh data containers (i.e. named JData nodes) can be defined using one of the two forms: an N-D array or a structure.

Array form

For simple data, one can use the "array form" to store the data under a JMesh keyword. In such case, the format of the data must follow the "N-Dimensional Array Storage Keyword" rules defined in the JData specification. For example, one can store a 1-D or 2-D array using the direct storage format as "jmesh_container_1d": [v1,v2,...,vn], "jmesh_container_2d": [[v11,v12,...,v1n], [v21,v22,...,v2n], ... [vm1,vm2,...,vmn] ]or using the "annotated storage" format as "jmesh_container_nd":

Structure form

One can also use a JData structure to store the primary data as well as to support additional metadata associated with the container. For example, a structure-based container may have the below subfields: "jmesh_container_struct": Only the "Data" subfield is required, and it must have the same data stored in the "array form" (either in direct or annotated format) as shown above.

The optional "Properties" subfield allows one to store additional data with this shape/mesh element. The "Properties" subfield can be an array or structure with additional subfields.

The optional "_DataInfo_" is the JData construct for storing metadata associated with this structure. It can be used to store simple metadata, such as data acquisition date, operator name, or version number. The strategies how to split the metadata between _DataInfo_ and Properties is user-dependent.

Summary of JMesh keywords

Most of the data container keywords associated with discretized geometries have a prefix of "Mesh"; keywords associated with parametric shape constructs have a prefix of "Shape"; keywords associated with constructive solid geometries have a prefix "CSG". Many of the keywords ends with a numerical value which typically represents the column number of the data when stored in the array format.

Mesh grouping: MeshGroup, MeshObject, MeshPart
Vertices: MeshVertex1,MeshVertex2,MeshVertex3,MeshVertex4
Lines: MeshLine,MeshEdge,MeshBSpline2D
Surfaces: MeshTri3,MeshQuad4,MeshPLC,MeshNURBS
Solid: MeshTet4,MeshHex8,MeshPyramid5,MeshTet10
Flexible containers: MeshNode,MeshSurf,MeshPoly,MeshElem
CSG operators: CSGObject,CSGUnion,CSGIntersect,CSGSubtract
Texture: Texture1D,Texture2D,Texture3D
2-D shape primitives: ShapeBox2,ShapeDisc2,ShapeEllipse,ShapeLine2, ShapeArrow2,ShapeAnnulus,ShapeGrid2
3-D shape primitives: ShapeLine3,ShapePlane3,ShapeBox3,ShapeDisc3, ShapeGrid3,ShapeSphere,ShapeCylinder,ShapeEllipsoid,ShapeTorus,ShapeCone, ShapeConeFrustum,ShapeSphereShell,ShapeSphereSegment
Extrusion and revolving: ShapeExtrude2D,ShapeExtrude3D,ShapeRevolve3D
Properties: Color,Normal,Size,Label,Value

Vertices

"MeshVertex1" defines a 1-D position vector. It must be defined as an N-by-1 or 1-by-N numerical vector, where N equals to the total number of vertices. The values in this vector shall be the coordinates of the 1-D vertices.

"MeshVertex1": [x1,x2,x3,...]

"MeshVertex2" defines a 2-D position vector. It must be defined as an N-by-2 numerical array where N is the total number of vertices. Each row of this array contains the coordinates of the vertex.

"MeshVertex2": [[x1,y1], [x2,y2], [x3,y3], ...]

"MeshVertex3" defines a 3-D position vector. Similar to MeshVertex2, it must be defined as an N-by-3 numerical array.

"MeshVertex3": [[x1,y1,z1], [x2,y2,z2], [x3,y3,z3], ...]

Line segments and curves

"MeshPolyLine" defines a set of line segments using an ordered 1-D list of node indices (starting from 1). It must be defined by an 1-by-N or N-by-1 vector of integers. If an index is 0, it marks the end of the current line segment and starts a new line segment from the next index.

"MeshPolyLine": [N1, N2, N3, ... ]

"MeshEdge" defines a set of line segments using a 2-D array with a pair of node indices in each row of the array. It must be defined by an N-by-2 integer array, where N is the total number of edges.

"MeshEdge": [[N11,N12], [N21,N22], [N31,N32], ...]

Surfaces

"MeshTri3" defines a discretized surface made of triangles with a triplet of node indices in each row of the array. It must be defined by an N-by-3 integer array, where N is the total number of triangles.

"MeshTri3": [[N11, N12, N13], [N21, N22, N23], [N31, N32, N33], ...]

"MeshQuad4" defines a discretized surface made of quadrilateral with a quadruplet of node indices in each row of the array. It must be defined by an N-by-4 integer array, where N is the total number of quadrilaterals.

"MeshQuad4": [[N11, N12, N13, N14], [N21, N22, N23, N24], [N31, N32, N33, N24], ...]

"MeshPLC" defines a discretized surface made of polygons (piecewise linear complex) of uniform or varied edge sizes. It must be defined by an array with elements of integer vectors of equal or varied lengths.

"MeshPLC": [[N11, N12, N13, ...], [N21, N22, N23, N24, ...], [N31, N32, N33, N34, ..., ...], ...]

Solid Elements

"MeshTet4" defines a discretized volumetric domain made of tetrahedral elements, with each element made of a quadruplet of node indices. It must be defined by an N-by-4 integer array, where N is the total number of tetrahedra.

"MeshTet4": [[N11, N12, N13, N14], [N21, N22, N23, N24], [N31, N32, N33, N34], ...]

"MeshHex8" defines a discretized volumetric domain made of 8-node hexahedral elements, with each element specified by a 8-tuple node index. It must be defined by an N-by-8 integer array, where N is the total number of hexahedra.

"MeshHex8": [[N11, N12, N13, ..., N18], [N21, N22, N23, ..., N28], [N31, N32, N33, ..., N28], ...]

"MeshPyramid5" defines a discretized volumetric domain made of 5-node pyramid elements, with each element specified by a 5-tuple node index. It must be defined by an N-by-5 integer array, where N is the total number of pyramid.

"MeshPyramid5": [[N11, N12, N13, ..., N15], [N21, N22, N23, ..., N25], [N31, N32, N33, ..., N25], ...]

"MeshTet10" defines a discretized volumetric domain made of 10-node straight-line tetrahedral elements, with each element specified by a 10-tuple node index. It must be defined by an N-by-10 integer array, where N is the total number of 10-node tetrahedra.

"MeshTet10": [[N11, N12, N13, ..., N1_10], [N21, N22, N23, ..., N2_10], [N31, N32, N33, ..., N2_10], ...]The first 4 columns of the array specifies the indices of the 4 vertices of the tetrahedron, identical to "MeshTet4", and the last 6 columns of the array specifies the mid-edge node indices, sorted in the below order: [N1, N2, N3, N4, N12, N13, N14, N22, N23, N34]

Flexible mesh data containers

Flexible mesh data containers allow one to encode a wide range of mesh data using a simple 2-D array.

"MeshNode" defines a flexible container for the storage of vertex coordinates and the associated properties. It must be defined by an N-by-M array, where N is the number of vertices, and M is the number of coordinates (D) plus the number of numerical properties (P) attached along each vertex, i.e. M = D + P

"MeshNode": [[x11, y11, z11, ..., w1D, ..., v11, v12, ..., v1P], [x21, y21, z21, ..., w2D, ..., v21, v22, ..., v2P], [x31, y31, z31, ..., w3D, ..., v31, v32, ..., v3P], ...]

"MeshSurf" defines a flexible container for the storage of fix-node-length surface patches and the associated properties. It must be defined by an N-by-M array, where N is the number of surface elements, and M is the number of vertices per element (K) plus the number of numerical properties (P) attached along each vertex, i.e. M = K + P

"MeshSurf": [[N11, N11, ..., N1K, ..., v11, v12, ..., v1P], [N21, N21, ..., N2K, ..., v21, v22, ..., v2P], [N31, N31, ..., N3K, ..., v31, v32, ..., v3P], ...]

"MeshPoly" defines a flexible container for the storage of variable-node-length surface patches and the associated properties. Similar to "MeshPLC", it must be defined by an array with elements of integer vectors, but it can contain additional metadata in each element. For each vector representing a surface patch, the first non-numerical entry, for example, a structure or sub-array, of the vector marks the start of the property data.

"MeshPoly": [[N11, N12, N13, ..., {properties}], [N21, N22, N23, N24, ...], [N31, N32, N33, N34, ..., ..., [properties] ], ...]

"MeshElem" defines a flexible container for the storage of volumetric elements and the associated properties. It must be defined by an N-by-M array, where N is the number of surface elements, and M is the number of vertices per element (K) plus the number of numerical properties (P) attached along each vertex, i.e. M = K + P

"MeshElem": [[N11, N11, ..., N1K, ..., v11, v12, ..., v1P], [N21, N21, ..., N2K, ..., v21, v22, ..., v2P], [N31, N31, ..., N3K, ..., v31, v32, ..., v3P], ...]

Shape primitives

ShapeBox2: A 2-D axis-aligned-bounding-box (AABB) defined by the two diagonal points ("O" as one end and "P" as the other end)

"ShapeBox2":

ShapeDisc2: A 2-D disc defined by the center ("O") and radius "r"

"ShapeDisc2":

ShapeEllipse: A 2-D ellipse defined by the center ("O"), x and y axes in the un-rotated coordinate system ("rx" and "ry"), and rotation angle "theta0"

"ShapeEllipse":

ShapeLine2: A 2-D line defined by one point along the line ("O"), and a 2-D vector ("V") aligns with the direction of the line

"ShapeLine2":

ShapeArrow2: A 2-D arrow object defined by one point along the line ("O"), and a 2-D vector ("V") aligns with the direction of the line, and the arrow-head size is indicated by scalar "s"

"ShapeArrow2":

ShapeAnnulus: A 2-D annulus defined by the center ("O"), and the outer radius (r1) and inner radius (r2)

"ShapeAnnulus":

ShapeGrid2: A 2-D grid defined by the one end of the diagonal line ("O"), and the other end ("P"); the numbers of segments along the first and second coordinates are indicated by "Nx" and "Ny", respectively

"ShapeGrid2":

ShapeLine3: A 3-D line defined by one point along the line ("O"), and a 3-D vector ("V") aligns with the direction of the line

"ShapeLine3":

ShapePlane3: A 3-D plane defined by one point along the line ("O"), and a 3-D vector ("N") pointing to the normal direction of the plane

"ShapePlane3":

ShapeBox3: A 3-D axis-aligned-bounding-box (AABB) defined by the two diagonal points ("O" as one end and "P" as the other end)

"ShapeBox3":

ShapeDisc3: A 3-D disc defined by the center ("O") and radius "R"; the normal direction of the disc is specified in "N"

"ShapeDisc3":

ShapeGrid3: A 3-D grid defined by the one end of the diagonal line ("O"), and the other end ("P"); the numbers of segments along the x/y/z coordinates are indicated by "Nx", "Ny" and "Nz", respectively

"ShapeGrid3":

ShapeSphere: A 3-D sphere defined by the center ("O") and radius "r"

"ShapeSphere":

ShapeCylinder: A 3-D cylinder defined by one end of the cylindrical axis ("O") and the other end of the axis "P"; the radius of the cylinder is specified in "r"

"ShapeCylinder":

ShapeEllipsoid: A 3-D ellipsoid defined by the center position ("O"), x, y and z axes in the pre-rotated coordinate system (rx, ry, rz), and the azimuthal rotation angle theta0 and zenith rotation angle phi0

"ShapeEllipsoid":

ShapeTorus: A 3-D torus defined by the center of the torus ("O"), the radius of the torus (r1) and the tube radius (r2) and the normal direction vector "N"

"ShapeTorus":

ShapeCone: A 3-D cone defined by the center of the bottom circle of the cone ("O"), the radius of the bottom circle (r) and the tip position "P"

"ShapeCone":

Software library

Because JMesh specification is defined base on the JData specification, it shares the same underlying data serialization formats, i.e. JSON for text-based JMesh files (.jmsh) and BJData/UBJSON for binary-based JMesh files (.bmsh). Most existing JSON parsers can readily parse the text-based JMesh files, and similarly, existing UBJSON parsers can be used to parse .bmsh files without modification.

In MATLAB/GNU Octave, saving mesh data to the JMesh format is supported in Iso2Mesh - a 3-D mesh generation toolbox - via the savejmesh function.

External links

Notes and References

Web site: JMesh Specification - Version 1 Draft 1. GitHub. 14 March 2022.
Web site: NeuroJSON/jmesh. GitHub. 14 March 2022.