{"id":19500194,"url":"https://github.com/cesiumgs/3d-tiles-validator","last_synced_at":"2025-05-14T19:03:18.759Z","repository":{"id":38362930,"uuid":"64871744","full_name":"CesiumGS/3d-tiles-validator","owner":"CesiumGS","description":"Validator for 3D Tiles :vertical_traffic_light:","archived":false,"fork":false,"pushed_at":"2025-02-24T16:09:23.000Z","size":9471,"stargazers_count":438,"open_issues_count":32,"forks_count":155,"subscribers_count":33,"default_branch":"main","last_synced_at":"2025-04-14T23:17:54.231Z","etag":null,"topics":["3d-tiles"],"latest_commit_sha":null,"homepage":"https://cesium.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CesiumGS.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-03T18:59:02.000Z","updated_at":"2025-04-10T11:37:33.000Z","dependencies_parsed_at":"2023-10-03T00:55:01.069Z","dependency_job_id":"ae8056f1-ceb0-443d-8c01-cca0bf0e40cc","html_url":"https://github.com/CesiumGS/3d-tiles-validator","commit_stats":{"total_commits":864,"total_committers":31,"mean_commits":"27.870967741935484","dds":0.6712962962962963,"last_synced_commit":"0e43590d2f8c784137b630032043420c58e94ee4"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CesiumGS%2F3d-tiles-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CesiumGS%2F3d-tiles-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CesiumGS%2F3d-tiles-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CesiumGS%2F3d-tiles-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CesiumGS","download_url":"https://codeload.github.com/CesiumGS/3d-tiles-validator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248975329,"owners_count":21192210,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-tiles"],"created_at":"2024-11-10T22:07:50.856Z","updated_at":"2025-04-14T23:18:12.461Z","avatar_url":"https://github.com/CesiumGS.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 3D Tiles Validator\n\nA validator for [3D Tiles](https://github.com/CesiumGS/3d-tiles).\n\n\u003e **A note about the repository structure**\n\u003e \n\u003e This repository originally contained multiple projects. Now, these projects are maintained in separate repositories:\n\u003e \n\u003e - The `3d-tiles-tools` can be found in [the `3d-tiles-tools` repository](https://github.com/CesiumGS/3d-tiles-tools)\n\u003e - The `3d-tiles-samples-generator` can be found in [the `3d-tiles-samples-generator` repository](https://github.com/CesiumGS/3d-tiles-samples-generator)\n\u003e \n\n## Overview\n\nThe 3D Tiles validator can be used to validate 3D Tiles tilesets and their associated tile content data. It supports version 1.0 and version 1.1 of the 3D Tiles specification. The validator can be used as a command line tool, or as a library.\n\n**Note**: Some of the implementation and interfaces may still change. This refers to the source code as well as details of the command line interface and report format.\n\n### Implemented Features \n\n- Validation of the JSON structure of the `tileset.json` file\n- Validation of the 3D Tiles [Tile Formats](https://github.com/CesiumGS/3d-tiles/tree/main/specification/TileFormats)\n  - The supported tile formats are: Batched 3D Model (`b3dm`), Instanced 3D Model (`i3dm`), Point Cloud (`pnts`), Composite (`cmpt`)\n  - glTF tile content is validated with the [glTF Validator](https://github.com/KhronosGroup/glTF-Validator)\n- Validation of implicit tilesets\n- Validation of 3D Tiles Metadata\n  - This includes the validation of the JSON structure of the metadata, as well as the structure and ranges of metadata values, both for the JSON based representation and for the binary metadata that is stored in property tables\n- A basic validation of the [`3DTILES_bounding_volume_S2` extension](https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_bounding_volume_S2)\n- Validation of tilesets that are contained in 3D Tiles package files (3TZ and 3DTILES files)\n\n## Installation\n\nIn order to install the validator locally into a directory, run\n```\nnpm install 3d-tiles-validator\n```\n(If you want to work directly with a clone of the Git repository, see [Developer Setup](#developer-setup))\n\n## Command Line Usage\n\n#### Validate a single tileset file\n```\nnpx 3d-tiles-validator --tilesetFile specs/data/Samples/SparseImplicitQuadtree/tileset.json\n```\n\nThe input file can either be a tileset JSON file, or one of the known tileset package files. The known package file formats are 3TZ (a package format based on ZIP), and 3DTILES (a package format based on SQLite). The type of the input is determined from the file extension, which may be `.3tz` or `.3dtiles` (case-insensitively). For example, to validate a 3TZ file:\n```\nnpx 3d-tiles-validator --tilesetFile ./specs/data/tilesets/packages/validTilesetPackage.3tz\n```\n\n#### Validate a set of tileset files\n```\nnpx 3d-tiles-validator --tilesetsDirectory specs/data/Samples/\n```\nThis will validate all tileset files in the given directory and all its subdirectories. The tileset files are identified by matching the file name against the glob pattern `**/*tileset*.json`. The pattern can be configured with the `tilesetGlobPattern` parameter. For example, in order to treat all .json files as tileset files:\n```\nnpx 3d-tiles-validator --tilesetsDirectory specs/data/Samples/ --tilesetGlobPattern **/*.json\n```\n\n#### Validate a tile content file\n```\nnpx 3d-tiles-validator --tileContentFile specs/data/gltfExtensions/FeatureIdAttributeAndPropertyTableFeatureIdNotInRange.gltf\n```\n\nThe input file can be any of the content types that are supported by the validator. This includes B3DM, I3DM, PNTS, CMPT, and glTF/GLB files. The type of the file will be determined, and if it is not a known type, then a validation warning will be created.\n\n### Report Files\n\nBy default, validation reports are printed to the console. \n\nWhen validating a single file, then the `reportFile` argument can be used to specify the output file for the validation report. For example:\n```\nnpx 3d-tiles-validator --tilesetFile specs/data/Samples/TilesetWithFullMetadata/tileset.json --reportFile MY_REPORT.json\n```\n\nAlternatively, or when validating multiple files, the `writeReports` argument can be used to write report files into the same directory as the input files. The name of the report file will be derived from the input file name. \n```\nnpx 3d-tiles-validator --tilesetsDirectory specs/data/Samples/ --writeReports\n```\n\n### Option Files\n\nOptions for the validation process can be specified in a file that is given via the `--optionsFile` argument: \n```\nnpx 3d-tiles-validator --optionsFile exampleOptions.json\n```\nThe options represent the properties of the `ValidationOptions` class. For example, using the following `exampleOptions.json` file, then the validator will only validate the tileset JSON structure, but _no_ tile content data:\n```JSON\n{\n  \"validateContentData\": false\n}\n```\nThe following options will cause the validator to _include_ B3DM- and GLB files in the validation process, but ignore all other content types:\n```JSON\n{\n  \"includeContentTypes\": [ \"CONTENT_TYPE_B3DM\", \"CONTENT_TYPE_GLB\" ]\n}\n```\nThe following options will cause the validator to _exclude_ tileset files (i.e. external tilesets) during the validation:\n```JSON\n{\n  \"excludeContentTypes\": [ \"CONTENT_TYPE_TILESET\" ]\n}\n```\n\nThe options can also be part of a configuration file, as described in the next section.\n\n\n### Configuration Files\n\nThe command line arguments for a validator run can be summarized in a configuration file that is given with the `--configFile` argument. For example, when running the validator with\n```\nnpx 3d-tiles-validator --configFile exampleConfig.json\n```\nusing the following `exampleConfig.json` file\n```JSON\n{\n  \"tilesetsDirectory\": \"specs/data/tilesets\",\n  \"tilesetGlobPattern\": \"**/*.json\"\n}\n```\nthen the validator will validate all files in the given directory that match the given glob pattern.\n\nThe configuration can also contain an `options` object. This object summarizes the validation options, as described in the [Option Files](#option-files) section. For example: \n```JSON\n{\n  \"tilesetsDirectory\": \"specs/data/tilesets\",\n  \"tilesetGlobPattern\": \"**/*.json\",\n  \"options\": {\n    \"includeContentTypes\": [ \"CONTENT_TYPE_B3DM\", \"CONTENT_TYPE_GLB\" ]\n  }\n}\n```\nThis will cause the validator to validate all JSON files in the specified directory, but only consider B3DM- and GLB tile content data during the validation.\n\n### Custom Metadata Semantics\n\nThe [3D Metadata Specification](https://github.com/CesiumGS/3d-tiles/tree/main/specification/Metadata) allows for the definition of custom _semantics_ for metadata properties. The built-in semantics are described in the [3D Metadata Semantic Reference](https://github.com/CesiumGS/3d-tiles/tree/main/specification/Metadata/Semantics). For other semantics, the validator will by default generate a `METADATA_SEMANTIC_UNKNOWN` issue. \n\nTo avoid these warnings, clients can define their own semantics in a metadata schema file, so that they are taken into account during the validation process. Some details of this process might still change (see [`3d-tiles/issues/643`](https://github.com/CesiumGS/3d-tiles/issues/643) for a discussion). But the current state of the support of metadata semantics validation in the 3D Tiles Validator is described here.\n\n#### Metadata Semantics Schema\n\nA 'semantics schema' is a [3D Metadata Schema](https://github.com/CesiumGS/3d-tiles/tree/main/specification/Metadata#schema) file that describes the _semantics_ that may appear in another metadata schema. In a semantics schema, the property names are just the names of the semantics. For example, when a client wants to define a semantic for a class like `ExampleClass`, and this semantic has the name `EXAMPLE_SEMANTIC`, then this structure can be represented in a semantics schema file as follows:\n\n**`exampleSemanticsSchema.json`:**\n```json\n{\n  \"id\": \"Example-Semantics-0.0.0\",\n  \"description\": \"A metadata schema where each class property has a name that represents one possible semantic of a metadata property, and that is used for validating semantics, by passing it in as one of the 'semanticSchemaFileNames' of the validation options\",\n  \"classes\": {\n    \"ExampleClassSemantics\": {\n      \"description\": \"A class where each property is a semantic for a property of the 'ExampleClass'\",\n      \"properties\": {\n        \"EXAMPLE_SEMANTIC\": {\n          \"name\": \"The 'EXAMPLE_SEMANTIC' structure\",\n          \"description\": \"The structure that a property must have so that it can have the 'EXAMPLE_SEMANTIC'\",\n          \"type\": \"SCALAR\",\n          \"componentType\": \"FLOAT32\"\n        }\n      }\n    }\n  }\n}\n```\n\n\u003e Note: \n\u003e \n\u003e This schema file contains elaborate names and descriptions. These are optional on a technical level. An equivalent schema file is\n\u003e ```json\n\u003e {\n\u003e   \"id\": \"Example-Semantics-0.0.0\",\n\u003e   \"classes\": {\n\u003e     \"ExampleClassSemantics\": {\n\u003e       \"properties\": {\n\u003e         \"EXAMPLE_SEMANTIC\": {\n\u003e           \"type\": \"SCALAR\",\n\u003e           \"componentType\": \"FLOAT32\"\n\u003e         }\n\u003e       }\n\u003e     }\n\u003e   }\n\u003e }\n\u003e ```\n\u003e But adding names and descriptions is strongly recommended for documentation purposes. \n\n#### Metadata Semantics Schema Registration\n\nIn order to include a 'semantics schema' in the validation process, the name of the schema file can be passed to the validator, as part of the validation options:\n\n**`exampleOptions.json`:**\n```json\n{\n  \"semanticSchemaFileNames\": [\"exampleSemanticsSchema.json\"]\n}\n```\n\nThis options file can then be passed to the validator:\n```\nnpx 3d-tiles-validator --optionsFile exampleOptions.json -t ./data/exampleTileset.json\n```\n\nThe validator will then validate the semantics that are defined in the tileset JSON against the structure that was defined in the semantics schema.\n\n\n\n## Developer Setup\n\nWhen the validator is not installed as a package from NPM, but supposed to be used directly in a cloned repository, then the command line usage is as follows:\n\n- Clone the repository into the current directory:\n  ```\n  git clone https://github.com/CesiumGS/3d-tiles-validator\n  ```\n- Change into the directory of the cloned repository:\n  ```\n  cd 3d-tiles-validator\n  ```\n- Install the validator and all its dependencies:\n  ```\n  npm install\n  ```\n\nAfter this, `ts-node` can be used to directly execute the validator, using the same command line options as described above - for example, to validate a single tileset file:\n```\nnpx ts-node src/main.ts --tilesetFile specs/data/Samples/SparseImplicitQuadtree/tileset.json\n```\n\n\n## Library Usage\n\nThe basic usage of the validator as a library is shown here:\n```JavaScript\nconst { Validators } = require(\"3d-tiles-validator\");\n\nconst resultPromise = Validators.validateTilesetFile(\"example.json\");\nresultPromise.then((result) =\u003e {\n  console.log(result.serialize());\n});\n```\nThe `Validators.validateTilesetFile` receives a file name, and returns a promise to the `ValidationResult`, which can then be printed to the console. The second (optional) parameter is a `ValidationOptions` object that summarizes the options for the validation process (also see [Option Files](#option-files)).\n\n### Validaton Result Filtering\n\nClients can perform basic filtering operations on a `ValidationResult`, in order to remove validation issues that are below a certain severity level, or warnings that are anticipated in a certain application context.\n\nFor example, a given validation result can be filtered to \n- include validation issues that have the severity `ERROR`\n- exclude validation issues that have the type `EXTENSION_NOT_SUPPORTED`\n\nAn example of applying such a filter to a given validation result is shown here:\n```JavaScript\nconst { Validators, ValidationIssueFilters, ValidationIssueSeverity } = require(\"3d-tiles-validator\");\n\nconst resultPromise = Validators.validateTilesetFile(\"example.json\");\nresultPromise.then((result) =\u003e {\n  const filteredResult = result\n    .filter(ValidationIssueFilters.byIncludedSeverities(ValidationIssueSeverity.ERROR))\n    .filter(ValidationIssueFilters.byExcludedTypes(\"EXTENSION_NOT_SUPPORTED\"));\n  console.log(filteredResult.serialize());\n});\n```\n\n**Note**: The `type` strings that are used for describing and categorizing the validation issues are not part of the core API. These strings might change between minor- or patch releases. But changes will be pointed out in the change log.\n\n## Implementation Notes\n\nSee [`IMPLEMENTATION.md`](IMPLEMENTATION.md) for implementation notes.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcesiumgs%2F3d-tiles-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcesiumgs%2F3d-tiles-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcesiumgs%2F3d-tiles-validator/lists"}