Merge pull request #5 from IIIF-Commons/draft3dapi

Bringing in the draft 3d changes to this repo

.codesandbox/ci.json

@@ -0,0 +1,6 @@
+{
+ "sandboxes": [
+ "vanilla-ts"
+ ],
+ "node": "16"
+}

.github/workflows/build-test.yml

@@ -7,7 +7,7 @@ jobs:
  runs-on: ubuntu-latest
  strategy:
  matrix:
- node: [ '16', '14' ]
+ node: [ '16' ]
 
  name: Node ${{ matrix.node }} build
  steps:
@@ -24,8 +24,8 @@ jobs:
  node-version: ${{ matrix.node }}
  - run: npm ci
  - run: npm run build
- - run: npm run test
+ # - run: npm run test
  # @todo these are not working currently.
  # - run: node pkg-tests/node-load.js
  # - run: node pkg-tests/node-load.mjs
- - run: node pkg-tests/node-umd.js
+ # - run: node pkg-tests/node-umd.js

.gitignore

@@ -1,9 +1,5 @@
-dist-commonjs
-dist-esmodule
-dist-umd
-dist-var
 coverage
 npm-debug.log
 node_modules
+dist
 debug.log
-types

.npmignore

@@ -2,4 +2,7 @@
 **/tsconfig.json
 **/webpack.config.js
 node_modules
-src
+src
+mocha_3d_tests.js
+test
+pkg-tests

README.md

@@ -1,29 +1,75 @@
 # manifesto
 
-[![Build Status](https://travis-ci.org/IIIF-Commons/manifesto.svg?branch=master)](https://travis-ci.org/IIIF-Commons/manifesto)
+Client and server utility library to support draft 3D extensions to to the IIIF Presentation API client and server utility library.
 
-IIIF Presentation API client and server utility library.
+Forked from [IIIF-Commons/manifesto](https://github.com/IIIF-Commons/manifesto).
 
- npm install manifesto.js --save
+Goal of implementing the [Draft API](https://github.com/IIIF/3d/blob/main/temp-draft-4.md) under development by the [IIIF 3D Technical Study Group](https://github.com/IIIF/3d/).
 
-## Getting Started
 
 ### Documentation
 
-https://iiif-commons.github.io/manifesto/
+[Manifesto.js](https://vincentmarchetti.github.io/manifesto/)
 
-### Developer Setup
+### Loading through package manager
 
- git clone https://github.com/iiif-commons/manifesto.git
- npm install
- npm build
- npm test
+This included in package.json
 
-### Publishing Package
+ "dependencies": {
+ "manifesto.js": "IIIF-Commons/manifesto#draft3dapi",
+ },
+
+will install manifesto modules into node_modules.
 
- git checkout master
- npm version patch
- git add .
- git commit -m "Release v1.2.3"
- git tag v1.2.3
- git push origin master v1.2.3
+### Demonstration Projects
+[Example manifests](https://github.com/IIIF/3d/tree/main/manifests) conforming to the [Draft API](https://github.com/IIIF/3d/blob/main/temp-draft-4.md) .
+
+[Prototype Viewers](https://github.com/IIIF/3d/issues/28) rendering the example manifests.
+- [Three-JS based viewer](https://codesandbox.io/p/github/JulieWinchester/iiif-threejs-demo)
+- [X3D/X3DOM based viewer](https://codesandbox.io/p/github/vincentmarchetti/iiif-x3dom-demo/main)
+- [Smithsonian Voyager](https://codesandbox.io/p/sandbox/voyager-annotations-demo-forked-l83l6w)
+
+### ChangeLog
+
+From start point of the version distributed from [JulieWinchester/manifesto](https://github.com/JulieWinchester/manifesto/tree/3dtsg-dev-dist)
+
+#### To package.json version 4.3.0-draft3dapi.0.1.0 
+distributed from [vincentmarchetti/manifesto#3dtsg-main]() there were these changes:
+
+1. This test is no longer useful for the Target of an Annotation:
+
+  if ( typeof(target) === "string" ){
+  // handle case where target is a Scene
+  }
+
+ Draft manifest [ 3_lights/direction_light_transform ]( https://github.com/IIIF/3d/blob/main/manifests/3_lights/direction_light_transform_rotate.json ) uses two ways of encoding the value of a target property for an Annotation: with a json string value of the IRI, or with an object with `id` property of the IRI for the Scene. To avoid exponential expansion of if-else code when combined with target property which can also be `SpecificResource` resources, the parsing code was changed so tha the value returned from `getTarget()` is always an object.
+
+ Since the Target property will always be an object referencing a `Scene`, or a `SpecificResource` whose `source` property is a `Scene`, the code for handling either would be
+
+ if (target.isSpecificResource){
+ // handle a SpecificResource, with selector property
+ // and whose source property is the Scene
+ }
+ else{
+ // handle a Scene directly
+ }
+
+2. Annotation.getBody3D() is deprecated.
+
+ The `Annotation.getBody()` from the Presentation 3 code has been extended to support the resources that can be included in a 3d Annotation body property. An important difference is that the `getBody()` function returns an array of objects, while the `getBody3D()` returns a single object. The deprecated function `getBody3D()` should be replaced with `getBody()[0]`
+
+#### To package.json version 4.3.0-draft3dapi.0.2.0
+
+1. Fixed a bug that occurred in determining the 'source' property of a SpecificResource resource that is the "target" property of an Annotation. This bug escaped detection previously because in the 3D case this 'source' property has always been a Scene resource, and the value is not needed for visualization. 
+
+#### To package.json version 4.3.0-draft3dapi.0.3.0
+
+1. Added isSpecificResource and isAnnotationBody properties to the SpecificResource and AnnotationBody classes, in response to developer suggestion. (Slack, Apr 24 2024)
+
+#### To package.json version 4.3.0-draft3dapi.0.4.0
+
+1. Implemented Perspective Camera properties in the Camera class.
+
+#### To package.json version 4.3.0-draft3dapi.0.5.0
+
+1. Implement lookAt property of Camera class and of Light class.

dist-commonjs/Annotation.d.ts

@@ -0,0 +1,56 @@
+import { AnnotationMotivation } from "@iiif/vocabulary/dist-commonjs";
+import { AnnotationBody, IManifestoOptions, ManifestResource, Resource, SpecificResource } from "./internal";
+import { Vector3 } from "threejs-math";
+export declare class Annotation extends ManifestResource {
+ constructor(jsonld: any, options: IManifestoOptions);
+ /**
+ In spite of its name, this method returns an array of objects, each of which
+ represents a potential body annotations
+ 
+ @see{ https://iiif.io/api/cookbook/recipe/0033-choice/ }
+ **/
+ getBody(): (AnnotationBody | SpecificResource)[];
+ get Body(): (SpecificResource | AnnotationBody)[];
+ /**
+ auxiliary function to getBody; intended to hande an object that has an element items
+ which is a array of annotation- body-like objects. This : https://iiif.io/api/cookbook/recipe/0033-choice/
+ seems to be the use case for this
+ **/
+ private parseBodiesFromItemsList;
+ /**
+ auxiliary function to parseBodiesFromItemsList and getBody, this is the last
+ step on recursively going through collections of bodies.
+ **/
+ private parseSingletonBody;
+ /**
+ Developer Note: 8 April 2024
+ getBody3D function was developed in the early stages of the 3D API Feb-March 2024
+ as alternative to the existing Annotation getBody function, but the signature for
+ getBody3D was chosen to be a single object instance, not an array.
+ 
+ At this stage, the merging of the 2D API anf the draft 3D API has been completed, so
+ 3D applications can use the getBody() function to retrieve the body of an Annotation intended
+ to target a scene. For compatibily the return value of the function is still an
+ array.
+ 
+ 3D clients using getBody are responsible for choosing the appropriate instance from the
+ returned array. In most cases this will be the sole 0th element.
+ **/
+ getBody3D(): (AnnotationBody | SpecificResource);
+ getMotivation(): AnnotationMotivation | null;
+ getOn(): string;
+ getTarget(): any;
+ get Target(): any;
+ getResource(): Resource;
+ /**
+ * A 3D point coordinate object for the location of an Annotation
+ * to satisfy the requirements of the lookAt property of camera and
+ * spotlight resources, according to the draft v4 API as of April 1 2024
+ *
+ * Is the position of the point for a target which is a SpecificResource with
+ * a PointSelector
+ * Otherwise, for example when the annotation target is an entire Scene, the
+ * location for lookAt is the origin (0,0,0)
+ **/
+ get LookAtLocation(): Vector3;
+}

dist-commonjs/AnnotationBody.d.ts

@@ -0,0 +1,23 @@
+import { ExternalResourceType, MediaType } from "@iiif/vocabulary/dist-commonjs";
+import { IManifestoOptions, ManifestResource } from "./internal";
+/**
+With the 3D extensions to the IIIF Presentation API the name of this
+class is misleading, but for now is being retained for the sake backward
+compatibility with earlier manifesto code and tests.
+
+The 3D extensions allow that the body property of an annotation can be
+a light, camera, or model, or a SpecificResource object wrapping a light, camera,
+or model.
+**/
+export declare class AnnotationBody extends ManifestResource {
+ constructor(jsonld?: any, options?: IManifestoOptions);
+ isAnnotationBody: boolean;
+ isSpecificResource: boolean;
+ getFormat(): MediaType | null;
+ getType(): ExternalResourceType | null;
+ getWidth(): number;
+ getHeight(): number;
+ isModel: boolean;
+ isLight: boolean;
+ isCamera: boolean;
+}