# VideoFrame - Video frame class for analysis
# Created per slot_fixes.yaml migration for: frame_sample_rate
# Creation date: 2026-01-22
#
# Rule compliance:
# - Rule 38: Slot centralization with semantic URIs
# - Rule 39: RiC-O temporal naming conventions
# - Rule 53: Generic reusable slots

id: https://nde.nl/ontology/hc/class/VideoFrame
name: VideoFrame
title: VideoFrame Class

prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  schema: http://schema.org/
  oa: http://www.w3.org/ns/oa#

imports:
  - linkml:types
  - ../slots/has_or_had_quantity
  - ../slots/has_or_had_unit
  - ./Quantity
  - ./Unit

default_prefix: hc

classes:
  VideoFrame:
    class_uri: schema:VideoObject
    description: |
      A video frame or set of frames analyzed during video processing.
      
      **PURPOSE**:
      Represents frames from a video that have been analyzed by computer vision
      or multimodal AI models. Used to track frame-based analysis parameters
      such as sample rate (frames per second analyzed) and total frames processed.
      
      **USE CASES**:
      - Video annotation (object detection, scene analysis)
      - Frame sampling configuration
      - Analysis throughput tracking
      - Computer vision pipeline configuration
      
      **FRAME SAMPLE RATE**:
      The sample rate determines how many frames are analyzed per second of video:
      
      | Sample Rate | Frames/sec | Use Case |
      |-------------|------------|----------|
      | 0.1 fps | 1 every 10s | Overview/thumbnails |
      | 1.0 fps | 1 per second | Standard analysis |
      | 5.0 fps | 5 per second | Detailed analysis |
      | 30.0 fps | Every frame | Exhaustive analysis |
      
      Higher sample rates capture more detail but increase compute cost.
      
      **MIGRATION SUPPORT**:
      This class supports migration from the frame_sample_rate slot per
      slot_fixes.yaml. Use with has_or_had_quantity + Quantity + has_or_had_unit + Unit.
      
    exact_mappings:
      - oa:Target
    
    close_mappings:
      - schema:VideoObject
    
    slots:
      - has_or_had_quantity
      - has_or_had_unit
    
    slot_usage:
      has_or_had_quantity:
        description: |
          Frame sample rate expressed as quantity with unit.
          MIGRATED from frame_sample_rate slot per slot_fixes.yaml (Rule 53, 2026-01-22).
          
          Use Quantity class with:
          - quantity_value: the numeric sample rate (e.g., 1.0, 5.0, 30.0)
          - quantity_type: FRAME_SAMPLE_RATE
          - has_or_had_unit: "samples per second" or "fps"
        range: Quantity
        inlined: true
        multivalued: false
        examples:
          - value: |
              quantity_value: 1.0
              quantity_type: FRAME_SAMPLE_RATE
              has_or_had_unit:
                unit_value: "samples per second"
            description: 1 frame per second sample rate
          - value: |
              quantity_value: 5.0
              quantity_type: FRAME_SAMPLE_RATE
              has_or_had_unit:
                unit_value: "fps"
                has_or_had_label:
                  - label_text: "frames per second"
            description: 5 fps sample rate
      has_or_had_unit:
        description: |
          Unit of measurement for frame sample rate.
          Typically "samples per second" or "fps".
        range: Unit
        inlined: true
    
    attributes:
      frame_count:
        range: integer
        description: |
          Total number of frames in this video or segment.
          Used for calculating total frames analyzed from sample rate.
        minimum_value: 0
      
      frame_width:
        range: integer
        description: Frame width in pixels.
        minimum_value: 1
      
      frame_height:
        range: integer
        description: Frame height in pixels.
        minimum_value: 1
    
    annotations:
      custodian_types: '["D"]'
      custodian_types_rationale: >-
        Video frames are primarily relevant for digital platforms (D) that
        host or process video content.
      custodian_types_primary: D
      specificity_score: 0.7
      specificity_rationale: >-
        Moderately specific - applies only to video analysis contexts.
    
    examples:
      - value: |
          VideoFrame:
            has_or_had_quantity:
              quantity_value: 1.0
              quantity_type: FRAME_SAMPLE_RATE
              has_or_had_unit:
                unit_value: "samples per second"
            frame_count: 1800
        description: Video analyzed at 1 fps over 30 minutes (1800 frames).
      
      - value: |
          VideoFrame:
            has_or_had_quantity:
              quantity_value: 5.0
              quantity_type: FRAME_SAMPLE_RATE
              has_or_had_unit:
                unit_value: "fps"
            frame_width: 1920
            frame_height: 1080
        description: 5 fps analysis of HD video.
    
    comments:
      - Created from slot_fixes.yaml migration (2026-01-22)
      - Use with analyzes_or_analyzed slot to track frame analysis
      - Sample rate affects both coverage and compute cost