mujoco-react 9.3.0 → 9.5.0

package/src/rendering/cameraFrameSource.ts

@@ -56,6 +56,27 @@ export interface ResolvedMountedCameraFrameSource {
   source: MountedCameraFrameCaptureSource;
 }
 
+export const MountedCameraFrameSourceSuggestionMatch = {
+  Direct: 'direct',
+  Alias: 'alias',
+  Normalized: 'normalized',
+  Prefix: 'prefix',
+  Suffix: 'suffix',
+  Contains: 'contains',
+} as const;
+
+export type MountedCameraFrameSourceSuggestionMatch =
+  (typeof MountedCameraFrameSourceSuggestionMatch)[keyof typeof MountedCameraFrameSourceSuggestionMatch];
+
+export interface MountedCameraFrameSourceSuggestion {
+  key: string;
+  selector: CameraFrameMountSelector;
+  source: MountedCameraFrameCaptureSource;
+  resourceName: string;
+  resourceKind: MountedCameraFrameCaptureSource['kind'];
+  match: MountedCameraFrameSourceSuggestionMatch;
+}
+
 export type MountedCameraFrameSequenceDefaults = Omit<
   CameraFrameSequenceCamera,
   'key' | 'cameraName' | 'siteName' | 'bodyName' | 'source'
@@ -123,6 +144,57 @@ export interface MountedCameraFrameSequenceRecordResult
   readiness: MountedCameraFrameSequenceReadiness;
 }
 
+export const MountedCameraFrameSequenceManifestStatus = {
+  Complete: 'complete',
+  Partial: 'partial',
+  Missing: 'missing',
+} as const;
+
+export type MountedCameraFrameSequenceManifestStatus =
+  (typeof MountedCameraFrameSequenceManifestStatus)[keyof typeof MountedCameraFrameSequenceManifestStatus];
+
+export interface MountedCameraFrameSequenceStreamSummary {
+  key: string;
+  ready: boolean;
+  complete: boolean;
+  status: MountedCameraFrameSequenceManifestStatus;
+  source?: CameraFrameCaptureSource;
+  selector?: CameraFrameMountSelector;
+  target?: string;
+  width?: number;
+  height?: number;
+  expectedFrameCount: number;
+  recordedFrameCount: number;
+  missingFrameCount: number;
+  firstFrameIndex: number | null;
+  lastFrameIndex: number | null;
+  firstTimestamp: number | null;
+  lastTimestamp: number | null;
+  message: string;
+}
+
+export interface CreateMountedCameraFrameSequenceManifestOptions {
+  expectedFrameCount?: number;
+  cameraKeys?: readonly string[];
+}
+
+export interface MountedCameraFrameSequenceManifest {
+  schema: 'mujoco-react/mounted-camera-frame-sequence-manifest@1';
+  ready: boolean;
+  complete: boolean;
+  status: MountedCameraFrameSequenceManifestStatus;
+  cameraKeys: string[];
+  resolvedKeys: string[];
+  missingKeys: string[];
+  expectedFrameCount: number;
+  recordedFrameCount: number;
+  missingFrameCount: number;
+  streamSummaries: Record<string, MountedCameraFrameSequenceStreamSummary>;
+  streams: MountedCameraFrameSequenceStreamSummary[];
+  readiness: MountedCameraFrameSequenceReadiness;
+  message: string;
+}
+
 export type MountedCameraFrameSequenceRecorderTarget = Pick<
   MujocoSimAPI,
   'getCameras' | 'getSites' | 'getBodies' | 'recordCameraSequence'
@@ -147,6 +219,16 @@ function createNameSet(
   );
 }
 
+function createResourceNames(
+  resources:
+    | readonly (string | NamedCameraFrameResource | null | undefined)[]
+    | undefined
+) {
+  return (resources ?? [])
+    .map((resource) => getResourceName(resource))
+    .filter((name): name is string => Boolean(name));
+}
+
 function normalizeAliasCandidates(
   value: CameraFrameMountSelector | readonly CameraFrameMountSelector[] | undefined
 ) {
@@ -160,6 +242,35 @@ function countMountedSelectors(selector: CameraFrameMountSelector) {
     Number(Boolean(selector.bodyName));
 }
 
+function normalizeCameraSourceName(value: string) {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+}
+
+function createCameraSourceKeyVariants(key: string) {
+  const candidates = [
+    key,
+    key.startsWith('observation.images.')
+      ? key.slice('observation.images.'.length)
+      : '',
+    key.includes('.') ? key.split('.').at(-1) ?? '' : '',
+    key.includes('/') ? key.split('/').at(-1) ?? '' : '',
+  ];
+  return candidates
+    .map((candidate) => candidate.trim())
+    .filter((candidate, index, items) => candidate && items.indexOf(candidate) === index);
+}
+
+function getSelectorKey(selector: CameraFrameMountSelector) {
+  if (selector.cameraName) return `camera:${selector.cameraName}`;
+  if (selector.siteName) return `site:${selector.siteName}`;
+  if (selector.bodyName) return `body:${selector.bodyName}`;
+  return null;
+}
+
 export function getMountedCameraFrameCaptureSource(
   selector: CameraFrameMountSelector
 ): MountedCameraFrameCaptureSource | null {
@@ -197,6 +308,66 @@ export function getCameraFrameCaptureSourceTarget(
   return 'fallback camera';
 }
 
+function createMountedCameraFrameSourceSuggestion(
+  key: string,
+  selector: CameraFrameMountSelector,
+  resourceName: string,
+  match: MountedCameraFrameSourceSuggestionMatch
+): MountedCameraFrameSourceSuggestion | null {
+  const source = getMountedCameraFrameCaptureSource(selector);
+  if (!source) return null;
+  return {
+    key,
+    selector,
+    source,
+    resourceName,
+    resourceKind: source.kind,
+    match,
+  };
+}
+
+function addMountedCameraFrameSourceSuggestion(
+  suggestions: MountedCameraFrameSourceSuggestion[],
+  seen: Set<string>,
+  suggestion: MountedCameraFrameSourceSuggestion | null
+) {
+  if (!suggestion) return;
+  const selectorKey = getSelectorKey(suggestion.selector);
+  if (!selectorKey || seen.has(selectorKey)) return;
+  seen.add(selectorKey);
+  suggestions.push(suggestion);
+}
+
+function getCameraFrameResourceMatch(
+  key: string,
+  resourceName: string
+): MountedCameraFrameSourceSuggestionMatch | null {
+  if (resourceName === key) return MountedCameraFrameSourceSuggestionMatch.Direct;
+
+  const normalizedResource = normalizeCameraSourceName(resourceName);
+  if (!normalizedResource) return null;
+
+  for (const variant of createCameraSourceKeyVariants(key)) {
+    if (resourceName === variant) return MountedCameraFrameSourceSuggestionMatch.Direct;
+
+    const normalizedKey = normalizeCameraSourceName(variant);
+    if (!normalizedKey) continue;
+    if (normalizedResource === normalizedKey) {
+      return MountedCameraFrameSourceSuggestionMatch.Normalized;
+    }
+    if (normalizedResource.startsWith(`${normalizedKey}_`)) {
+      return MountedCameraFrameSourceSuggestionMatch.Prefix;
+    }
+    if (normalizedResource.endsWith(`_${normalizedKey}`)) {
+      return MountedCameraFrameSourceSuggestionMatch.Suffix;
+    }
+    if (normalizedResource.includes(`_${normalizedKey}_`)) {
+      return MountedCameraFrameSourceSuggestionMatch.Contains;
+    }
+  }
+  return null;
+}
+
 function isSelectorMounted(
   selector: CameraFrameMountSelector,
   cameraNames: Set<string>,
@@ -211,6 +382,82 @@ function isSelectorMounted(
   );
 }
 
+export function createMountedCameraFrameSourceSuggestions(
+  key: string,
+  options: ResolveMountedCameraFrameSourceOptions
+): MountedCameraFrameSourceSuggestion[] {
+  const cameraNames = createNameSet(options.cameras);
+  const siteNames = createNameSet(options.sites);
+  const bodyNames = createNameSet(options.bodies);
+  const suggestions: MountedCameraFrameSourceSuggestion[] = [];
+  const seen = new Set<string>();
+
+  for (const selector of normalizeAliasCandidates(options.aliases?.[key])) {
+    if (!isSelectorMounted(selector, cameraNames, siteNames, bodyNames)) {
+      continue;
+    }
+    const source = getMountedCameraFrameCaptureSource(selector);
+    if (!source) continue;
+    addMountedCameraFrameSourceSuggestion(
+      suggestions,
+      seen,
+      createMountedCameraFrameSourceSuggestion(
+        key,
+        selector,
+        getCameraFrameCaptureSourceTarget(source),
+        MountedCameraFrameSourceSuggestionMatch.Alias
+      )
+    );
+  }
+
+  for (const cameraName of createResourceNames(options.cameras)) {
+    const match = getCameraFrameResourceMatch(key, cameraName);
+    if (!match) continue;
+    addMountedCameraFrameSourceSuggestion(
+      suggestions,
+      seen,
+      createMountedCameraFrameSourceSuggestion(
+        key,
+        { cameraName },
+        cameraName,
+        match
+      )
+    );
+  }
+
+  for (const siteName of createResourceNames(options.sites)) {
+    const match = getCameraFrameResourceMatch(key, siteName);
+    if (!match) continue;
+    addMountedCameraFrameSourceSuggestion(
+      suggestions,
+      seen,
+      createMountedCameraFrameSourceSuggestion(
+        key,
+        { siteName },
+        siteName,
+        match
+      )
+    );
+  }
+
+  for (const bodyName of createResourceNames(options.bodies)) {
+    const match = getCameraFrameResourceMatch(key, bodyName);
+    if (!match) continue;
+    addMountedCameraFrameSourceSuggestion(
+      suggestions,
+      seen,
+      createMountedCameraFrameSourceSuggestion(
+        key,
+        { bodyName },
+        bodyName,
+        match
+      )
+    );
+  }
+
+  return suggestions;
+}
+
 export function resolveMountedCameraFrameSource(
   key: string,
   options: ResolveMountedCameraFrameSourceOptions
@@ -224,9 +471,8 @@ export function resolveMountedCameraFrameSource(
     { bodyName: key },
   ];
   const aliasCandidates = normalizeAliasCandidates(options.aliases?.[key]);
-  const candidates = [...directCandidates, ...aliasCandidates];
 
-  for (const selector of candidates) {
+  for (const selector of aliasCandidates) {
     if (!isSelectorMounted(selector, cameraNames, siteNames, bodyNames)) {
       continue;
     }
@@ -235,6 +481,15 @@ export function resolveMountedCameraFrameSource(
     return { key, selector, source };
   }
 
+  const [suggestion] = createMountedCameraFrameSourceSuggestions(key, options);
+  if (suggestion) {
+    return {
+      key,
+      selector: suggestion.selector,
+      source: suggestion.source,
+    };
+  }
+
   if (options.allowAliasFallback) {
     for (const selector of aliasCandidates) {
       const source = getMountedCameraFrameCaptureSource(selector);
@@ -243,6 +498,15 @@ export function resolveMountedCameraFrameSource(
     }
   }
 
+  for (const selector of directCandidates) {
+    if (!isSelectorMounted(selector, cameraNames, siteNames, bodyNames)) {
+      continue;
+    }
+    const source = getMountedCameraFrameCaptureSource(selector);
+    if (!source) continue;
+    return { key, selector, source };
+  }
+
   return null;
 }
 
@@ -335,6 +599,122 @@ export function createMountedCameraFrameSequenceReadiness(
   };
 }
 
+function normalizeFrameCount(frameCount: number | undefined) {
+  return Number.isFinite(frameCount) && frameCount !== undefined
+    ? Math.max(0, Math.floor(frameCount))
+    : 0;
+}
+
+export function createMountedCameraFrameSequenceManifest(
+  result: MountedCameraFrameSequenceRecordResult,
+  options: CreateMountedCameraFrameSequenceManifestOptions = {}
+): MountedCameraFrameSequenceManifest {
+  const cameraKeys = [
+    ...(options.cameraKeys ??
+      result.readiness.cameraKeys ??
+      result.plan.cameraKeys ??
+      result.cameraKeys),
+  ];
+  const expectedFrameCount = normalizeFrameCount(
+    options.expectedFrameCount ?? result.frameCount
+  );
+  const recordedFrameCount = normalizeFrameCount(result.frameCount);
+  const streamSummaries: Record<string, MountedCameraFrameSequenceStreamSummary> =
+    {};
+  const streams: MountedCameraFrameSequenceStreamSummary[] = [];
+  let missingFrameCount = 0;
+  let completeStreamCount = 0;
+  let resolvedOrRecordedStreamCount = 0;
+
+  for (const key of cameraKeys) {
+    const summary = result.cameraSummaries[key];
+    const readiness = result.readiness.cameras[key];
+    const source = summary?.source ?? readiness?.source;
+    const ready = readiness?.ready ?? Boolean(summary);
+    const recorded = normalizeFrameCount(summary?.frameCount);
+    const missing = Math.max(expectedFrameCount - recorded, 0);
+    const complete = ready && missing === 0;
+    const status = complete
+      ? MountedCameraFrameSequenceManifestStatus.Complete
+      : ready || recorded > 0
+        ? MountedCameraFrameSequenceManifestStatus.Partial
+        : MountedCameraFrameSequenceManifestStatus.Missing;
+    const target = source
+      ? getCameraFrameCaptureSourceTarget(source)
+      : readiness?.message
+        ? undefined
+        : 'missing MuJoCo camera';
+    const message = complete
+      ? `Camera stream "${key}" recorded ${recorded} of ${expectedFrameCount} frame${
+          expectedFrameCount === 1 ? '' : 's'
+        }.`
+      : ready || recorded > 0
+        ? `Camera stream "${key}" recorded ${recorded} of ${expectedFrameCount} frame${
+            expectedFrameCount === 1 ? '' : 's'
+          }.`
+        : readiness?.message ??
+          `Camera stream "${key}" did not record any frames.`;
+    const stream = {
+      key,
+      ready,
+      complete,
+      status,
+      source,
+      selector: readiness?.selector,
+      target,
+      width: summary?.width,
+      height: summary?.height,
+      expectedFrameCount,
+      recordedFrameCount: recorded,
+      missingFrameCount: missing,
+      firstFrameIndex: summary?.firstFrameIndex ?? null,
+      lastFrameIndex: summary?.lastFrameIndex ?? null,
+      firstTimestamp: summary?.firstTimestamp ?? null,
+      lastTimestamp: summary?.lastTimestamp ?? null,
+      message,
+    };
+
+    streamSummaries[key] = stream;
+    streams.push(stream);
+    missingFrameCount += missing;
+    if (complete) completeStreamCount += 1;
+    if (ready || recorded > 0) resolvedOrRecordedStreamCount += 1;
+  }
+
+  const complete =
+    result.readiness.ready &&
+    streams.length === completeStreamCount &&
+    missingFrameCount === 0;
+  const status = complete
+    ? MountedCameraFrameSequenceManifestStatus.Complete
+    : resolvedOrRecordedStreamCount > 0
+      ? MountedCameraFrameSequenceManifestStatus.Partial
+      : MountedCameraFrameSequenceManifestStatus.Missing;
+
+  return {
+    schema: 'mujoco-react/mounted-camera-frame-sequence-manifest@1',
+    ready: result.readiness.ready,
+    complete,
+    status,
+    cameraKeys,
+    resolvedKeys: [...result.readiness.resolvedKeys],
+    missingKeys: [...result.readiness.missingKeys],
+    expectedFrameCount,
+    recordedFrameCount,
+    missingFrameCount,
+    streamSummaries,
+    streams,
+    readiness: result.readiness,
+    message: complete
+      ? `All ${cameraKeys.length} camera stream${
+          cameraKeys.length === 1 ? '' : 's'
+        } recorded ${expectedFrameCount} frame${
+          expectedFrameCount === 1 ? '' : 's'
+        }.`
+      : `Mounted camera sequence coverage is ${status}.`,
+  };
+}
+
 export function createMountedCameraFrameSequencePlanFromApi(
   api: MountedCameraFrameSequenceRecorderTarget,
   cameraKeys: readonly string[],