Initial draft of 3D Tiles 1.1 validator

.gitignore

@@ -1,22 +1,3 @@
-# NPM
-node_modules/
-npm-debug.log
+node_modules
 package-lock.json
 
-# WebStorm user-specific
-.idea/workspace.xml
-.idea/tasks.xml
-
-# Generated files
-.nyc_output
-.eslintcache
-coverage
-output
-*.tgz
-*.zip
-
-# ts
-dist/
-
-# Generated documentation
-doc/

IMPLEMENTATION.md

@@ -0,0 +1,98 @@
+# 3D Tiles Validator 1.1 Implementation Notes
+
+Parts of the current implementation are still in a **DRAFT** state. 
+
+## Directory structure:
+
+- `./src`: The entry point for the command line interface is in `main.ts`
+- `./src/validation`: The core classes for the 3D Tiles validation
+- `./src/base`: Generic, low-level utility functions
+- `./src/io`: Classes for reading and resolving resources via URIs
+- `./src/issues`: Classes defining the categories of detected issues
+- `./src/structure`: Plain old objects for the 3D Tiles types
+- `./src/tileFormats`: Validators for tile content
+
+- `./src/json`: Classes for generic JSON-schema based validation. This currently only contains an implementation based on `ajv` that is used for internal verification. This is supposed to be extended to support JSON-schema based validation of extensions, with some sort of a "plugin" concept. 
+
+- Work in progress: 
+  - `./src/implicitTiling`: Classes that support accessing implicit tiling information
+  - `./src/traversal`: Classes for traversing tilesets
+  - `./src/metadata`: Classes that support accessing 3D Metadata
+
+- `./specs`: Jasmine spec drafts
+- `./specs/data`: Test data
+
+## Overview
+
+The classes in the `./src/validation` directory are the core classes for the 3D Tiles validation. 
+
+The entry point for the tileset validation is the `TilesetValidator` class:
+
+- It receives a tileset JSON string and parses it into a `structure/Tileset.ts` object.
+  - Note: These `structure/*` classes are "plain objects". The do not have methods, and no real type checking. They _only_ hold the parsed data.
+- It traverses the `Tileset` structure, and performs the validation
+  - For each object type, there is a validator, like `AssetValidator`, `ContentValidator`, `TileValidator`, `BoundingVolumeValidator` etc. For now, these are mainly classes with single static functions, but they might be refined for some objects.
+
+Each validation function receives a `ValidationContext` as the last parameter. 
+
+The `ValidationContext` class:
+
+- Can contain configuration options that may be needed in the future (like `doValidateContents=false` or so)
+- Maintains a `ResourceResolver` that reads a `Buffer` from a given URI (resolved in the respective context - the tileset, external tileset, or glTF)
+- Collects the `ValidationIssue` instances (errors and warnings) that are found during the traversal
+
+The `ValidationIssue` class and its types:
+
+- The `ValidationIssue` itself is a plain data structure with basic info about the issue (message, path, severity...)
+- Instances of this class are created with methods in the `issues*` classes, roughly categorized here:
+  - `issues/IoValidationIssues.ts`: Fundamental IO errors, like `JSON_PARSE_ERROR`
+  - `issues/JsonValidationIssues.ts`: Violations of the JSON schema, like `PROPERTY_MISSING` or `ARRAY_LENGTH_MISMATCH`
+  - `issues/StructureValidationIssues.ts`: General issues related to an inconsistent structure, like `IDENTIFIER_NOT_FOUND` 
+  - `issues/SemanticValidationIssues.ts`: Issues related to inconsistent property values, like `TILE_GEOMETRIC_ERROR_INCONSISTENT` 
+  - `ContentValidationIssues.ts`: An error or warning in a tile content
+- For validation issues that refer to the tile content, each `ValidationIssue` can have an array of `internalIssues`. This can be filled, for example, with the information from the glTF validator that caused the validation to fail
+
+## Discussion points
+
+### General functionality
+
+- It should be possible to "batch process" a directory (with caveats - how to detect whether a file is a `tileset.json`, beyond its name?)
+- It should be possible to write reports into files.
+
+### Validation Options
+
+There are certain settings that one could imagine for the validation process. It should be possible to configure the validator accordingly. One also could consider an option to ignore certain issues, like `validator.ignore("/ ** /content/uri", PROPERTY_MISSING)`. But it would be necessary to check these 'ignored issues' literally _everywhere_. It would probably make more sense to offer a `filter` operation on the `ValidationResult`. 
+
+### Test approaches 
+
+The current state of the testing is that there is bunch of tilesets with all kinds of issues in the `./specs/data` directory, and a `ValidationIssuesSpec.ts` that should test the validation issues:
+- Run the validation on each file from the `specs/data` directory
+- Check whether the actual issues match the expected ones
+
+It _might_ make sense to describe these tests in a more structured form, where each "spec" could contain a summary like this:
+```
+  {
+    "fileName": "assetVersionInvalidType.json",
+    "description": "The tileset.asset.version does not have the type `string`",
+    "expected": [
+      {
+        "type": "TYPE_MISMATCH",
+        "severity": 0
+      }
+    ]
+  },
+```
+These tests could then be processed programmatically, and things like the `description` may be useful as a documentation for more complex issues. But it would no longer use the Jasmine infrastructure (e.g. for running individual tests, and certain forms of reports). 
+
+
+### JSON Schema Based Validation
+
+The initial approach for the JSON schema based validation was to simply use the `ajv` library. This has some caveats, and has therefore been replaced with a manual validation of the schema compliance. However, there should be a mechansim for supporting JSON Schema based validation on demand - for example, for extensions that are not otherwise integrated into the validator. The `src/json` subdirectory contains some drafts for this. But in order to properly integrate this, some architectural questions will have to be answered, as well as the question where exactly the `.*schema.json` files will be stored. Eventually, the mechanism for adding a specific validation could/should boil down to a call like `validator.register("/node/**/boundingVolume", new ExtensionSchemaValidator("s2.schema"));`
+
+
+
+### Random Notes
+
+- The functions in `BasicValidator` should be made more consistent (see note at top of file). The functions should better reflect the `JsonValidationIssues`. The convenience functions that have been introduced (and will be introduced) should be used consistently at the call sites.
+- There should be a generic solution for the validation of enum values. When there are extensions, then their set may not be fixed (and the glTF validator hasn't sorted that out either). For example, there may be a `componentType` like `UINT128` or `FLOAT16` at some point in time...
+- The `extras` and `extensions` are not yet validated (this will just be the JSON-level check whether their properties are `object`s)

README.md

@@ -1,22 +1,69 @@
-<p align="center"><img src="figures/Cesium3DTiles.png" /></p>
+# 3D Tiles Validator 1.1
 
-Validator and sample data for [3D Tiles](https://github.com/CesiumGS/3d-tiles/blob/main/README.md) tilesets.
+A **draft** implementation of a validator for 3D Tiles 1.1.
 
-| Tool | Description |
-| :--- | :--- |
-| [3D Tiles Validator](./validator/) | Open source Node.js library and command-line tools for validating that a tileset conforms to the 3D Tiles specification. |
-| [3D Tiles Samples](./samples-generator/) | Open source command-line tools for generating sample 3D Tiles in [3d-tiles-samples](https://github.com/CesiumGS/3d-tiles-samples) |
+## Usage
 
-Created by the <a href="https://cesium.com/">Cesium team</a> and University of Pennsylvania students.
+**Note**: The command line interface is preliminary. It will change based on the feedback and desired functionality for passing in validiation configuration settings!
 
-To generate new 3D tilesets, see [Cesium ion](https://cesium.com/ion/).
+#### Validate a single tileset file:
+```
+npx ts-node src/main.ts --tilesetFile specs/data/Tilesets/TilesetWithFullMetadata/tileset.json
+```
 
-## Contributions
+#### Validate a single metadata schema file:
+```
+npx ts-node src/main.ts --metadataSchemaFile specs/data/schemas/validSchema.json
+```
 
-Pull requests are appreciated!  Please use the same [Contributor License Agreement (CLA)](https://github.com/CesiumGS/cesium/blob/main/CONTRIBUTING.md) and [Coding Guide](https://github.com/CesiumGS/cesium/blob/main/Documentation/Contributors/CodingGuide/README.md) used for [CesiumJS](https://cesium.com/cesiumjs/).
+#### Validate a single subtree file:
 
----
+**Note:** For the actual validation of standalone subtree files, there has to be a mechanism for passing in the information about the expected _structure_ of the subtree (namely, the information from the `implicitTiling` object). This example only refers to the files in the `specs` directory, which all assume the same subtree structure for now.
+```
+npx ts-node src/main.ts --subtreeFile specs/data/subtrees/binarySubtreeValid.subtree
+```
+
+#### Batch runs for the spec files
+
+The `specs/data` directory contains sample files that cause different validation issues. These files can be processed with
+```
+npx ts-node src/main.ts --tilesetSpecs
+npx ts-node src/main.ts --metadataSchemaSpecs
+npx ts-node src/main.ts --subtreeSpecs
+```
+
+## Reports
+
+Validation reports are currently printed to the console. Options to write them into files may be added later. For example, validating an tileset from the `specs/data` directory like this:
+```
+npx ts-node src/main.ts --tilesetFile specs/data/validTilesetWithInvalidB3dm.json
+```
+may print a validation report like this:
+```
+{
+  "date": "2022-09-21T18:41:45.562Z",
+  "numErrors": 1,
+  "numWarnings": 0,
+  "issues": [
+    {
+      "type": "CONTENT_VALIDATION_ERROR",
+      "path": "tiles/b3dm/invalid.b3dm",
+      "message": "Content tiles/b3dm/invalid.b3dm caused validation errors",
+      "severity": "ERROR",
+      "internalIssues": [
+        {
+          "type": "BINARY_INVALID_VALUE",
+          "path": "tiles/b3dm/invalid.b3dm",
+          "message": "The version must be 1 but is 2",
+          "severity": "ERROR"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Implementation notes
+
+See [`IMPLEMENTATION.md`](IMPLEMENTATION.md) for implementation notes.
 
-<p align="center">
-<a href="https://cesium.com/"><img src="figures/cesium.png" /></a>
-</p>