Skip to content

Commit 49ce5b4

Browse files
stephenwfstephenwf
committed
TEMP
1 parent 00724d3 commit 49ce5b4

13 files changed

Lines changed: 1603 additions & 0 deletions

‎src/presentation-4/README.md‎

Lines changed: 394 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,394 @@
1+
# IIIF Presentation API 4.0 Implementation
2+
3+
This directory contains the implementation of IIIF Presentation API 4.0 for the parser. Version 4.0 introduces significant new capabilities including 3D content support, enhanced temporal handling, and dynamic content states.
4+
5+
## Overview
6+
7+
The Presentation API 4.0 brings major architectural changes and new features:
8+
9+
### Key New Features
10+
11+
- **3D Content Support**: Scenes, Models, Cameras, Lights, Audio Emitters
12+
- **Enhanced Container Types**: Timeline (temporal), Canvas (2D+temporal), Scene (3D+temporal)
13+
- **Advanced Selectors**: PointSelector, WktSelector, AnimationSelector, etc.
14+
- **Content States**: Dynamic scene modification and storytelling capabilities
15+
- **Physical Dimensions**: Real-world scale mapping via `spatialScale` and `temporalScale`
16+
- **Interactive Annotations**: `activating` motivation for user interactions
17+
- **Enhanced Media Support**: Better audio/video handling with positioning
18+
19+
### Breaking Changes from v3
20+
21+
1. **Container Model**: Canvas is now one of three container types (Timeline, Canvas, Scene)
22+
2. **3D Coordinate System**: Right-handed Cartesian (positive Y up, positive X right, positive Z forward)
23+
3. **New Required Properties**: Timeline requires `duration`, Scene may have `duration`
24+
4. **Motivation Changes**: New `contentState` and `activating` motivations
25+
5. **Behavior Enhancements**: New behavior values for 3D interactions and temporal control
26+
27+
## Architecture
28+
29+
### Directory Structure
30+
31+
```
32+
presentation-4/
33+
├── README.md # This file
34+
├── index.ts # Main exports
35+
├── empty-types.ts # Default/empty entity definitions for v4
36+
├── normalize.ts # Normalization logic for v4 entities
37+
├── traverse.ts # Traversal logic for v4 resources
38+
├── serialize.ts # Base serialization utilities
39+
├── serialize-presentation-4.ts # v4 output serialization
40+
├── serialize-presentation-3.ts # v4→v3 downgrade serialization
41+
├── upgrade-from-v3.ts # v3→v4 upgrade utilities
42+
├── utilities.ts # v4-specific utility functions
43+
├── strict-upgrade.ts # Validation and strict upgrading
44+
└── types/ # TypeScript type definitions
45+
├── containers.ts # Timeline, Canvas, Scene types
46+
├── content-resources.ts # Model, Audio, Video, etc.
47+
├── scene-components.ts # Cameras, Lights, Audio Emitters
48+
├── selectors.ts # New selector types
49+
├── transforms.ts # Transform types
50+
└── extended-properties.ts # New v4 properties
51+
```
52+
53+
## Implementation Plan
54+
55+
### Phase 1: Core Infrastructure (Foundation)
56+
57+
**Goal**: Basic v4 parsing and normalization
58+
59+
1. **Type Definitions**
60+
- Define v4-specific TypeScript interfaces
61+
- Extend base types for new containers (Timeline, Scene)
62+
- Define 3D-specific types (Camera, Light, Transform, etc.)
63+
64+
2. **Empty Types & Defaults**
65+
- Create default objects for all new v4 entities
66+
- Timeline, Scene, Camera, Light, AudioEmitter defaults
67+
- New selector defaults (PointSelector, WktSelector, etc.)
68+
69+
3. **Basic Normalization**
70+
- Parse v4 JSON into normalized entities
71+
- Handle new container types in traversal
72+
- Basic validation of required properties
73+
74+
4. **Utility Functions**
75+
- 3D coordinate system utilities
76+
- Physical dimension conversion helpers
77+
- Content state resolution utilities
78+
79+
**Deliverables:**
80+
- `types/*.ts` - All v4 type definitions
81+
- `empty-types.ts` - Default entities
82+
- `utilities.ts` - Core utilities
83+
- Basic `normalize.ts` structure
84+
85+
### Phase 2: Traversal & Serialization (Core Logic)
86+
87+
**Goal**: Complete v4 processing pipeline
88+
89+
1. **Enhanced Traversal**
90+
- Support Timeline, Canvas, Scene traversal
91+
- Handle 3D content resources (Models, Cameras, Lights)
92+
- Process new selector types
93+
- Content state annotation processing
94+
95+
2. **Native v4 Serialization**
96+
- Output clean v4 JSON
97+
- Handle all new properties and structures
98+
- Maintain annotation structure integrity
99+
- Support content state serialization
100+
101+
3. **Validation & Strict Upgrading**
102+
- Validate v4 requirements
103+
- Check coordinate system consistency
104+
- Verify required properties for new containers
105+
106+
**Deliverables:**
107+
- Complete `traverse.ts`
108+
- `serialize-presentation-4.ts`
109+
- `strict-upgrade.ts`
110+
- Core `normalize.ts` implementation
111+
112+
### Phase 3: Bidirectional Conversion (Compatibility)
113+
114+
**Goal**: Seamless conversion between v3 and v4
115+
116+
1. **v3 → v4 Upgrade**
117+
- Convert v3 Canvases to v4 Canvases
118+
- Handle manifest structure changes
119+
- Preserve all v3 functionality
120+
- Add default v4 properties where needed
121+
122+
2. **v4 → v3 Downgrade**
123+
- Convert v4 back to v3 (excluding 3D features)
124+
- Map Timelines to v3 Canvases with duration
125+
- Strip 3D-only features gracefully
126+
- Preserve semantic meaning where possible
127+
- Handle content state graceful degradation
128+
129+
3. **Compatibility Layer**
130+
- Automatic detection of v3 vs v4 content
131+
- Seamless API for consuming applications
132+
- Migration utilities for existing data
133+
134+
**Deliverables:**
135+
- `upgrade-from-v3.ts`
136+
- `serialize-presentation-3.ts` (downgrade)
137+
- Migration documentation
138+
- Compatibility test suite
139+
140+
### Phase 4: Advanced Features (Enhancement)
141+
142+
**Goal**: Full v4 feature support
143+
144+
1. **Content State Processing**
145+
- Dynamic scene modification
146+
- Scope-based content states
147+
- Reset and cumulative behaviors
148+
- Linear navigation support
149+
150+
2. **3D Scene Composition**
151+
- Nested scene support
152+
- Transform application
153+
- Camera and lighting management
154+
- Audio positioning
155+
156+
3. **Interactive Features**
157+
- Activating annotation processing
158+
- Animation selector support
159+
- Hotspot and interaction handling
160+
161+
4. **Physical Dimensions**
162+
- Scale conversion utilities
163+
- Real-world measurement support
164+
- Cross-container scaling
165+
166+
**Deliverables:**
167+
- Advanced content state processing
168+
- 3D composition utilities
169+
- Interaction handlers
170+
- Physical dimension calculators
171+
172+
## Conversion Strategy
173+
174+
### v3 → v4 Upgrade
175+
176+
```typescript
177+
// Example upgrade logic
178+
function upgradeManifestV3ToV4(v3Manifest: ManifestV3): ManifestV4 {
179+
return {
180+
...v3Manifest,
181+
'@context': 'http://iiif.io/api/presentation/4/context.json',
182+
items: v3Manifest.items.map(canvas => upgradeCanvasV3ToV4(canvas))
183+
};
184+
}
185+
186+
function upgradeCanvasV3ToV4(v3Canvas: CanvasV3): CanvasV4 {
187+
return {
188+
...v3Canvas,
189+
type: 'Canvas', // Explicit container type
190+
// duration preserved if present
191+
// Add v4-specific defaults
192+
};
193+
}
194+
```
195+
196+
### v4 → v3 Downgrade
197+
198+
```typescript
199+
// Example downgrade logic
200+
function downgradeManifestV4ToV3(v4Manifest: ManifestV4): ManifestV3 {
201+
return {
202+
...v4Manifest,
203+
'@context': 'http://iiif.io/api/presentation/3/context.json',
204+
items: v4Manifest.items
205+
.filter(isV3Compatible) // Remove Scenes, unsupported features
206+
.map(container => downgradeContainerV4ToV3(container))
207+
};
208+
}
209+
210+
function downgradeContainerV4ToV3(container: ContainerV4): CanvasV3 {
211+
switch (container.type) {
212+
case 'Timeline':
213+
// Convert Timeline to Canvas with duration, default dimensions
214+
return {
215+
...container,
216+
type: 'Canvas',
217+
width: 1, // Minimal dimensions for temporal content
218+
height: 1,
219+
duration: container.duration
220+
};
221+
case 'Canvas':
222+
// Direct mapping, remove v4-only properties
223+
return stripV4Properties(container);
224+
case 'Scene':
225+
// Scenes cannot be downgraded - would need special handling
226+
throw new Error('Scene containers cannot be downgraded to v3');
227+
}
228+
}
229+
```
230+
231+
## Usage Examples
232+
233+
### Parsing v4 Content
234+
235+
```typescript
236+
import { normalize as normalizeV4 } from './presentation-4';
237+
238+
// Parse v4 manifest
239+
const v4Manifest = await fetch('https://example.org/manifest-v4.json').then(r => r.json());
240+
const { entities, resource, mapping } = normalizeV4(v4Manifest);
241+
242+
// Access 3D scene
243+
const scene = entities.Scene[resource.items[0].id];
244+
const cameras = scene.items.filter(item =>
245+
entities.Annotation[item.id]?.body?.type?.includes('Camera')
246+
);
247+
```
248+
249+
### Converting Between Versions
250+
251+
```typescript
252+
import { upgradeFromV3, serialize } from './presentation-4';
253+
import { serializeConfigPresentation3 } from './serialize-presentation-3';
254+
255+
// Upgrade v3 to v4
256+
const v3Manifest = await fetch('https://example.org/manifest-v3.json').then(r => r.json());
257+
const v4Normalized = upgradeFromV3(v3Manifest);
258+
259+
// Downgrade v4 to v3 (excluding 3D features)
260+
const v3Compatible = serialize(v4Normalized.entities, v4Normalized.resource, serializeConfigPresentation3);
261+
```
262+
263+
### Working with 3D Content
264+
265+
```typescript
266+
// Process Scene with 3D models
267+
const scene = entities.Scene[sceneId];
268+
const modelAnnotations = scene.items
269+
.flatMap(page => entities.AnnotationPage[page.id]?.items || [])
270+
.map(annoId => entities.Annotation[annoId])
271+
.filter(anno => anno?.body?.type === 'Model');
272+
273+
// Extract camera positions
274+
const cameras = scene.items
275+
.flatMap(page => entities.AnnotationPage[page.id]?.items || [])
276+
.map(annoId => entities.Annotation[annoId])
277+
.filter(anno => anno?.body?.type?.includes('Camera'))
278+
.map(anno => ({
279+
camera: anno.body,
280+
position: anno.target.selector // PointSelector with x,y,z
281+
}));
282+
```
283+
284+
## Configuration Options
285+
286+
### Serialization Configs
287+
288+
```typescript
289+
// Native v4 output
290+
import { serializeConfigPresentation4 } from './serialize-presentation-4';
291+
292+
// v3 compatible output (downgrade)
293+
import { serializeConfigPresentation3 } from './serialize-presentation-3';
294+
295+
// Custom config with specific feature toggles
296+
const customConfig = {
297+
...serializeConfigPresentation4,
298+
stripUnsupported3DFeatures: true,
299+
preserveContentStates: false,
300+
downgradeScenesToCanvas: true
301+
};
302+
```
303+
304+
### Upgrade Options
305+
306+
```typescript
307+
interface UpgradeOptions {
308+
preserveV3Semantics: boolean; // Keep v3-style behavior
309+
addDefaultV4Properties: boolean; // Add v4 defaults
310+
enableContentStates: boolean; // Process content state annotations
311+
enable3DFeatures: boolean; // Support Scene containers
312+
}
313+
```
314+
315+
## Development Guidelines
316+
317+
### Code Organization
318+
319+
1. **Separation of Concerns**: Keep v3 and v4 completely separate
320+
2. **Type Safety**: Use strict TypeScript for all v4 types
321+
3. **Backwards Compatibility**: Always provide graceful degradation
322+
4. **Testing**: Comprehensive test coverage for conversions
323+
324+
### Naming Conventions
325+
326+
- v4-specific files: `*-presentation-4.ts`
327+
- Downgrade files: `*-presentation-3.ts` (in v4 directory)
328+
- Upgrade utilities: `upgrade-from-v3.ts`
329+
- Type files: `types/*.ts`
330+
331+
### Error Handling
332+
333+
- Graceful degradation for unsupported features
334+
- Clear error messages for invalid v4 content
335+
- Validation warnings for missing required properties
336+
- Conversion logs for debugging
337+
338+
## Testing Strategy
339+
340+
### Unit Tests
341+
- Individual function testing for normalization
342+
- Serialization round-trip testing
343+
- Type validation testing
344+
345+
### Integration Tests
346+
- Full manifest processing pipelines
347+
- v3↔v4 conversion accuracy
348+
- Real-world manifest compatibility
349+
350+
### Performance Tests
351+
- Large manifest processing
352+
- Memory usage optimization
353+
- Conversion speed benchmarks
354+
355+
### Compatibility Tests
356+
- Cross-version feature matrix
357+
- Edge case handling
358+
- Error condition testing
359+
360+
## Future Considerations
361+
362+
### Potential Shared Utilities
363+
364+
After initial implementation, consider extracting shared utilities:
365+
366+
- **Language map processing**: Common between v3/v4
367+
- **URI validation**: Same across versions
368+
- **Basic annotation processing**: Core logic unchanged
369+
- **JSON-LD context handling**: Similar patterns
370+
371+
### Extension Points
372+
373+
- Custom selector support
374+
- Additional 3D content types
375+
- Enhanced content state behaviors
376+
- Community-defined motivations
377+
378+
### Performance Optimizations
379+
380+
- Lazy loading of 3D content
381+
- Efficient coordinate system transformations
382+
- Streaming processing for large scenes
383+
- Memory-efficient entity storage
384+
385+
## Migration Path
386+
387+
For existing applications:
388+
389+
1. **Phase 1**: Add v4 support alongside existing v3
390+
2. **Phase 2**: Migrate to v4 parsing with v3 output
391+
3. **Phase 3**: Enable v4 features incrementally
392+
4. **Phase 4**: Full v4 native implementation
393+
394+
This approach ensures zero-downtime migration and gradual feature adoption.

0 commit comments

Comments
 (0)