diff --git a/README.md b/README.md index a03ca4a..baa4be5 100644 --- a/README.md +++ b/README.md @@ -4,30 +4,44 @@ MediaWiki extension for using model-viewer to display and annotate 3D models ## Metadata -Model-viewer configurations and annotations can be added as a json string in the file's description. +Model-viewer configurations and annotations can be added as TOML in the file's description. ### Viewer Configuration -Configuration of the model-viewer instance is contained in the `viewerConfig` object. +Configuration of the model-viewer instance is contained in the `[viewerConfig]` object. This object can contain any number of child objects each of which describes a different possible configuration. Each configuration can have properties matching the any of the attributes of the model-viewer element except for `src`, `class`, `interpolation-delay`, and `interaction-prompt`. +If adding a poster image, the value of the `poster` property must be the name of an image in the Wiki's File namespace (without the namespace header, e.g., `"My poster.jpg"`). ### Annotations -Annotations can be configured using the `annotations` object. +Annotations can be configured using the `[annotations]` object. This object can contain any number of child objects each of which describes a different possible annotation. -The label for each annotation is the name of the child object. Each object has two required properties and two optional properties. +The label for each annotation is the name of the child object (`[annotations."Label here"]`). Each object has two required properties and three optional properties. | Property | Required | Description | Example | |----------|----------|-------------|---------| -| `data-position` | Yes | String containing the X, Y, and Z coordinates of the annotation. | "0.02297m -0.02544m 0.01780m" | -| `data-normal` | Yes | String containing the X, Y, and Z coordinates of the normal vector of the annotation. | "0.78966m -0.53116m 0.30709m" | -| `data-orbit` | No | String containing the orbit vector of the camera to view annotation. | "2.31rad 2.01rad 0.65m" | -| `data-target` | No | String containing the X, Y, and Z coordinates of the camera target to view annotation. | "-0.01029m 0.00071m 0.01138m" | +| **data-position** | Yes | String containing the X, Y, and Z coordinates of the annotation. | "0.02297m -0.02544m 0.01780m" | +| **data-normal** | Yes | String containing the X, Y, and Z coordinates of the normal vector of the annotation. | "0.78966m -0.53116m 0.30709m" | +| **data-orbit** | No | String containing the orbit vector of the camera to view annotation. | "2.31rad 2.01rad 0.65m" | +| **data-target** | No | String containing the X, Y, and Z coordinates of the camera target to view annotation. | "-0.01029m 0.00071m 0.01138m" | +| **field-of-view** | No | String containing the angle of the field of view in degrees. | "35.25deg" | ### Annotation sets Annotations sets are specific subsets of the listed annotations that can be shown on the model. -They are configured using the `annotationSets` object. -This object can contain any number of child objects each of which contains an array of strings matching the names of the annotation to be included. +They are configured using the `[annotationSets]` object. +This object can contain any number properties each of which contains an array of strings matching the names of the annotation to be included. +The property name is used as the annotation set identifier. By default, all annotations are rendered on a model. + +## Linking + +When adding the model file to a page, use the standard `[[File:Model name.glb]]` internal file link. +The link supports three optional properties. + +| Property | Description | Default | +|----------|-------------|---------| +| **view** | Use one of the non-default configurations specified in the `[viewerConfig]` object. | default viewer configuration | +| **set** | Display only the annotations listed in the specified annotation set from the `[annotationSets]` object. | show all annotations | +| **transform** | Reorder the displayed annotations. Can be either *rand* or *alpha*. | annotations are numbered in the order they are listed in the `[annotations]` object | \ No newline at end of file