2.4.0

dist/declarations/ngl.d.ts

@@ -126,6 +126,7 @@ import './parser/mrc-parser';
 import './parser/xplor-parser';
 import './parser/kin-parser';
 import './parser/obj-parser';
+import './parser/ply-parser';
 import './parser/csv-parser';
 import './parser/json-parser';
 import './parser/msgpack-parser';

dist/declarations/parser/ply-parser.d.ts

@@ -1,44 +1,151 @@
+import SurfaceParser from "./surface-parser";
+import { BufferGeometry, Color } from "three";
 /**
- * @file Ply Parser
- * @author Alexander Rose <alexander.rose@weirdbyte.de>
- * @private
- */
-import SurfaceParser from './surface-parser';
-/**
- * PLYLoader
- * @class
- * @private
- * @author Wei Meng / http://about.me/menway
+ * Port of PLYLoader from the MIT-licensed three.js project:
+ * https://github.com/mrdoob/three.js/blob/97b5d428d598228cae9b206d9a321f18d53a3e86/examples/jsm/loaders/PLYLoader.js
+ *
+ * The original code has been modified to work with NGL and TypeScript.
+ * Adaptation by @fredludlow
  *
- * @description
- * A THREE loader for PLY ASCII files (known as the Polygon File Format or the Stanford Triangle Format).
+ * Description: A THREE loader for PLY ASCII files (known as the Polygon
+ * File Format or the Stanford Triangle Format).
  *
  * Limitations: ASCII decoding assumes file is UTF-8.
  *
- * @example
- * var loader = new THREE.PLYLoader();
- * loader.load('./models/ply/ascii/dolphins.ply', function (geometry) {
- * scene.add( new THREE.Mesh( geometry ) );
- * } );
+ * Usage:
+ * const loader = new PLYLoader();
+ * loader.load('./models/ply/ascii/dolphins.ply', function (geometry) {
+ *
+ * scene.add( new THREE.Mesh( geometry ) );
+ *
+ * } );
  *
- * // If the PLY file uses non standard property names, they can be mapped while
- * // loading. For example, the following maps the properties
- * // “diffuse_(red|green|blue)” in the file to standard color names.
+ * If the PLY file uses non standard property names, they can be mapped while
+ * loading. For example, the following maps the properties
+ * “diffuse_(red|green|blue)” in the file to standard color names.
  *
  * loader.setPropertyNameMapping( {
- * diffuse_red: 'red',
- * diffuse_green: 'green',
- * diffuse_blue: 'blue'
+ * diffuse_red: 'red',
+ * diffuse_green: 'green',
+ * diffuse_blue: 'blue'
+ * } );
+ *
+ * Custom properties outside of the defaults for position, uv, normal
+ * and color attributes can be added using the setCustomPropertyNameMapping method.
+ * For example, the following maps the element properties “custom_property_a”
+ * and “custom_property_b” to an attribute “customAttribute” with an item size of 2.
+ * Attribute item sizes are set from the number of element properties in the property array.
+ *
+ * loader.setCustomPropertyNameMapping( {
+ * customAttribute: ['custom_property_a', 'custom_property_b'],
  * } );
  *
  */
-export interface _PLYLoader {
+declare const dataTypes: readonly ["int8", "char", "uint8", "uchar", "int16", "short", "uint16", "ushort", "int32", "int", "uint32", "uint", "float32", "float", "float64", "double"];
+declare type DataType = (typeof dataTypes)[number];
+interface HeaderText {
+ headerText: string;
+ headerLength: number;
+}
+interface BasePLYProperty {
+ type: DataType;
+ name: string;
+ valueReader?: BinaryReader;
+}
+interface SinglePLYProperty extends BasePLYProperty {
+ isList: false;
+}
+interface BinarySinglePLYProperty extends SinglePLYProperty {
+ valueReader: BinaryReader;
+}
+interface ListPLYProperty extends BasePLYProperty {
+ isList: true;
+ countType: DataType;
+ countReader?: BinaryReader;
+}
+interface BinaryListPLYProperty extends ListPLYProperty {
+ countReader: BinaryReader;
+ valueReader: BinaryReader;
+}
+declare type PLYProperty = SinglePLYProperty | ListPLYProperty;
+declare type BinaryPLYProperty = BinarySinglePLYProperty | BinaryListPLYProperty;
+interface PLYElement {
+ name: string;
+ count: number;
+ properties: PLYProperty[];
+ x: number;
+ y: number;
+ z: number;
+ red: number;
+ green: number;
+ blue: number;
+ [k: string]: any;
+}
+declare type PLYElementSpec = Pick<PLYElement, 'name' | 'count' | 'properties'>;
+interface PLYHeader {
+ format: string;
+ version: string;
+ comments: string[];
+ elements: PLYElementSpec[];
+ headerLength: number;
+ objInfo: string;
+}
+/** JS object that we generate the buffer from */
+interface PLYBuffer {
+ indices: number[];
+ vertices: number[];
+ normals: number[];
+ uvs: number[];
+ faceVertexUvs: number[];
+ colors: number[];
+ faceVertexColors: number[];
+ [k: string]: number[];
+}
+declare type BinaryReader = {
+ read: (at: number) => number;
+ size: number;
+};
+declare class PLYLoader {
  propertyNameMapping: {
  [k: string]: string;
  };
+ customPropertyMapping: {
+ [k: string]: string;
+ };
+ _color: Color;
+ constructor();
+ setPropertyNameMapping(mapping: {
+ [k: string]: string;
+ }): void;
+ createBuffer(): PLYBuffer;
+ extractHeaderText(bytes: Uint8Array): HeaderText;
+ handleElement(buffer: PLYBuffer, elementName: string, element: PLYElement, cacheEntry: MappedAttributes): void;
+ parse(data: string | ArrayBuffer): BufferGeometry;
+ parseHeader(data: string, headerLength?: number): PLYHeader;
+ parseASCII(data: string, header: PLYHeader): BufferGeometry;
+ parseBinary(data: Uint8Array, header: PLYHeader): BufferGeometry;
+ postProcess(buffer: PLYBuffer): BufferGeometry;
+ /** Augments properties with their appropriate valueReader attribute and
+ * countReader if the property is a list type
+ */
+ makeBinaryProperties(properties: PLYProperty[], body: DataView, little_endian: boolean): BinaryPLYProperty[];
 }
+declare function mapElementAttributes(properties: PLYProperty[]): {
+ attrX: string;
+ attrY: string;
+ attrZ: string;
+ attrNX: string | null;
+ attrNY: string | null;
+ attrNZ: string | null;
+ attrS: string | null;
+ attrT: string | null;
+ attrR: string | null;
+ attrG: string | null;
+ attrB: string | null;
+};
+declare type MappedAttributes = ReturnType<typeof mapElementAttributes>;
 declare class PlyParser extends SurfaceParser {
  get type(): string;
- getLoader(): _PLYLoader;
+ getLoader(): PLYLoader;
 }
 export default PlyParser;

package.json

@@ -1,6 +1,6 @@
 {
  "name": "ngl",
- "version": "2.3.1",
+ "version": "2.4.0",
  "description": "Scalable molecular graphics for the web",
  "main": "dist/ngl.umd.js",
  "module": "dist/ngl.esm.js",