Edit Hyper-Dataset preview information

docs/hyperdatasets/previews.md

@@ -2,98 +2,53 @@
 title: Previews
 ---
 
-A `preview` is a dictionary containing metadata for optional thumbnail images or videos that can be used in the ClearML Enterprise
+Previews are optional images or videos that can be used in the ClearML Enterprise
-WebApp (UI) to view selected content in a Dataset. `previews` includes the `uri` of the thumbnail image or video.
+WebApp (UI) to help visualize selected content in a Hyper-Dataset.
 
-Previews are not mandatory. Their primary use is to view images with formats that cannot be displayed in a web browser 
+They are useful for displaying images with formats that cannot be rendered in a web browser 
-(such as TIFF and 3D formats).  
+(such as TIFF and 3D formats), or to provide an alternative visual representation of the data.
 
-## Example
+In a Hyper-Dataset frame, the `source` typically points to the original raw data used for training or experimentation, 
+while the `preview_uri` is intended for display in the UI.
 
-The following is an example of preview metadata.
+Previews appear in the following WebApp pages: 
+* [Dataset version page](webapp/webapp_datasets_versioning.md): As thumbnails representing each frame in the dataset version. 
+  If a `preview_uri` is provided, it will be used for the thumbnail. Otherwise, the frame's source is shown. 
+  
+  ![Previews](../img/hyperdatasets/dataset_versions.png#light-mode-only)
+  ![Previews](../img/hyperdatasets/dataset_versions_dark.png#dark-mode-only)
 
-```json
+  If the `preview_uri` points to a video, the thumbnail includes video controls:
-"preview": {
-        "content_type": "image/jpg",
-        "uri": "https://s3.amazonaws.com/my_previews/car_1/front_preview.jpg",
-        "timestamp": 0
-    }
-```
 
-<Collapsible type="configuration" title="View an entire frame containing a preview">
+  ![Video previews](../img/hyperdatasets/video_preview.png#light-mode-only)
+  ![Video previews](../img/hyperdatasets/video_preview_dark.png#dark-mode-only)
+ 
+* [Frame viewer](webapp/webapp_datasets_frames.md): When inspecting a single frame, the frame viewer lets you toggle between the 
+  `source` and the `preview_uri` if both are provided and differ. If no `preview_uri` is provided, the frame's source is 
+  shown.  
 
-```json
+  ![Use source toggle](../img/hyperdatasets/source_preview.png#light-mode-only)
-{
+  ![Use source toggle](../img/hyperdatasets/source_preview_dark.png#dark-mode-only)
-    "timestamp": 1234567889,
-    "context_id": "car_1",
-    "meta": {
-        "velocity": "60"
-    },
-    "sources": [
-        {
-            "id": "front",
-            "content_type": "video/mp4",
-            "width": 800,
-            "height": 600,
-            "uri": "https://s3.amazonaws.com/my_cars/car_1/front.mp4",
-            "timestamp": 1234567889,
-            "meta" :{
-                "angle":45,
-                "fov":129
-            },
-            "preview": {
-                "content_type": "image/jpg",
-                "uri": "https://s3.amazonaws.com/my_previews/car_1/front_preview.jpg",
-                "timestamp": 0
-            },
-            "masks": [
-                {
-                    "id": "seg",
-                    "content_type": "video/mp4",
-                    "uri": "https://s3.amazonaws.com/seg_masks/car_1/front_seg.mp4",
-                    "timestamp": 1234567889
-                },
-                {
-                    "id": "instances_seg",
-                    "content_type": "video/mp4",
-                    "uri": "https://s3.amazonaws.com/seg_masks/car_1/front_instance_seg.mp4",
-                    "timestamp": 1234567889
-                }
-            ]
-        },
-        {
-            "id": "rear",
-            "uri": "https://s3.amazonaws.com/my_cars/car_1/rear.mp4",
-            "content_type": "video/mp4",
-            "timestamp": 1234567889
-        }
-    ],
-    "rois": [
-        {
-            "sources": ["front"],
-            "label": ["bike"],
-            "poly":[30, 50, 50,50, 100,50, 100,100],
-            "meta": {
-               "velocity": 5.4
-            }
-        },
-        {
-            "sources": ["front", "rear"],
-            "label": ["car"],
-            "poly":[30, 50, 50,50, 100,50, 100,100]
-        }
-    ]
-}
-```
 
-</Collapsible>
+## Usage
 
-Here's an example of Previews in the ClearML Enterprise WebApp (UI). Each thumbnail is a Preview:
+### Register Frames with a Preview 
 
-![Previews](../img/hyperdatasets/dataset_versions.png#light-mode-only)
+To register frames with a preview,set the `preview_uri` when creating the frame:
-![Previews](../img/hyperdatasets/dataset_versions_dark.png#dark-mode-only)
 
-If the preview's `uri` is for a video, the thumbnail will display the video with video controls:
+```python
+# create dataset version
+version = DatasetVersion.create_version(
+ dataset_name="Example",
+ version_name="Registering frame with preview"
+)
 
-![Video previews](../img/hyperdatasets/video_preview.png#light-mode-only)
+frame = SingleFrame(
-![Video previews](../img/hyperdatasets/video_preview_dark.png#dark-mode-only)
+    source='https://acme-datasets.s3.amazonaws.com/tutorials/000012.jpg', 
+    width=512, height=512, 
+    preview_uri='https://acme-datasets.s3.amazonaws.com/images/000012.jpg'
+)
+
+# add frame to version
+version.add_frames([frame])
+```

docs/hyperdatasets/single_frames.md

@@ -42,8 +42,8 @@ For more information, see [Masks](masks.md).
 
 
 ### Previews 
-`previews` is a dictionary containing metadata for optional thumbnail images that can be used in the ClearML Enterprise WebApp (UI) 
+Previews are optional images or videos that can be used in the ClearML Enterprise WebApp (UI) 
-to view selected images in a Hyper-Dataset. `previews` includes the `uri` of the thumbnail image.
+to view images in a Hyper-Dataset. 
 
 For more information, see [Previews](previews.md).
 

docs/hyperdatasets/webapp/webapp_datasets_frames.md

@@ -45,7 +45,7 @@ Use frame viewer controls to navigate between frames in a Hyper-Dataset Version,
 |<img src="/docs/latest/icons/ico-arrow-right.svg" alt="Next frame icon" className="icon size-md space-sm" />|Go to the next frame | Right arrow |
 |<img src="/docs/latest/icons/ico-skip-next.svg" alt="Jump to next unfiltered annotation" className="icon size-md space-sm" />|Go to the next frame containing a non-filtered annotation (same filter as <img src="/docs/latest/icons/ico-skip-previous.svg" alt="Jump to previous unfiltered annotation" className="icon size-md space-sm" />).| <img src="/docs/latest/icons/ico-optional-no.svg" alt="Not applicable" className="icon size-md center-md" /> |
 |<img src="/docs/latest/icons/ico-skip-forward.svg" alt="Jump forwards icon" className="icon size-md space-sm" />|Jump forwards ten frames | CTRL + Right arrow |
-|`Use Source Data`|Show the frame’s `source` rather than its `preview_uri`| <img src="/docs/latest/icons/ico-optional-no.svg" alt="Not applicable" className="icon size-md center-md" /> |
+|`Use Source Data`|Show the frame's `source` rather than its `preview`| <img src="/docs/latest/icons/ico-optional-no.svg" alt="Not applicable" className="icon size-md center-md" /> |
 |<img src="/docs/latest/icons/ico-revert.svg" alt="Reload frame icon" className="icon size-md space-sm" />|Reload the frame.| <img src="/docs/latest/icons/ico-optional-no.svg" alt="Not applicable" className="icon size-md center-md" /> |
 |<img src="/docs/latest/icons/ico-undo.svg" alt="Undo icon" className="icon size-md space-sm" />|Undo changes.|Ctrl + Z| 
 |<img src="/docs/latest/icons/ico-redo.svg" alt="Redo icon" className="icon size-md space-sm" />|Redo changes.|Ctrl + Y|