cesiumjs-anywidget 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

cesiumjs_anywidget/widget.py

@@ -4,6 +4,9 @@ import os
 import pathlib
 import anywidget
 import traitlets
+from .logger import get_logger
+
+logger = get_logger(__name__)
 
 
 class CesiumWidget(anywidget.AnyWidget):
@@ -12,6 +15,7 @@ class CesiumWidget(anywidget.AnyWidget):
     This widget provides an interactive 3D globe with support for:
     - Camera position control (latitude, longitude, altitude)
     - Terrain and imagery visualization
+    - Google Photorealistic 3D Tiles (global photorealistic base layer)
     - Entity management (markers, shapes, models)
     - Bidirectional state synchronization between Python and JavaScript
 
@@ -59,6 +63,16 @@ class CesiumWidget(anywidget.AnyWidget):
     enable_lighting = traitlets.Bool(False, help="Enable scene lighting").tag(sync=True)
     show_timeline = traitlets.Bool(True, help="Show timeline widget").tag(sync=True)
     show_animation = traitlets.Bool(True, help="Show animation widget").tag(sync=True)
+    
+    # Photorealistic 3D Tiles options
+    enable_photorealistic_tiles = traitlets.Bool(
+        False, 
+        help="Enable Google Photorealistic 3D Tiles (global photorealistic base layer)"
+    ).tag(sync=True)
+    show_globe = traitlets.Bool(
+        True,
+        help="Show the base globe (set to False when using photorealistic tiles)"
+    ).tag(sync=True)
 
     # Cesium Ion access token (optional, uses default if not set)
     ion_access_token = traitlets.Unicode("", help="Cesium Ion access token").tag(
@@ -79,6 +93,12 @@ class CesiumWidget(anywidget.AnyWidget):
         help="List of CZML documents to display",
     ).tag(sync=True)
 
+    # CZML entity updates for dynamic property changes
+    czml_entity_update = traitlets.Dict(
+        default_value={},
+        help="Update properties of existing CZML entities (entity_id, property_name, value)"
+    ).tag(sync=True)
+
     # Interaction event data - sent when user interaction ends
     interaction_event = traitlets.Dict(
         default_value={},
@@ -103,6 +123,27 @@ class CesiumWidget(anywidget.AnyWidget):
         help="SkyBox rendering settings (show, sources for cube map faces)"
     ).tag(sync=True)
 
+    # Clock/Timeline configuration
+    current_time = traitlets.Unicode(
+        "",
+        help="Current time in ISO 8601 format (e.g., '2023-08-01T14:30:00Z')"
+    ).tag(sync=True)
+    
+    clock_multiplier = traitlets.Float(
+        1.0,
+        help="Animation speed multiplier (1.0 = real-time, 60.0 = 60x speed)"
+    ).tag(sync=True)
+    
+    should_animate = traitlets.Bool(
+        False,
+        help="Whether the clock should animate (play/pause)"
+    ).tag(sync=True)
+    
+    clock_command = traitlets.Dict(
+        default_value={},
+        help="Clock control commands (setTime, play, pause, setMultiplier)"
+    ).tag(sync=True)
+
     # Camera commands (for advanced camera operations)
     camera_command = traitlets.Dict(
         default_value={},
@@ -124,10 +165,43 @@ class CesiumWidget(anywidget.AnyWidget):
         default_value={}, help="Trigger to focus on a specific measurement"
     ).tag(sync=True)
     show_measurement_tools = traitlets.Bool(
-        default_value=True, help="Show or hide measurement toolbar"
+        default_value=False, help="Show or hide measurement toolbar"
     ).tag(sync=True)
     show_measurements_list = traitlets.Bool(
-        default_value=True, help="Show or hide measurements list panel"
+        default_value=False, help="Show or hide measurements list panel"
+    ).tag(sync=True)
+
+    # Debug mode for JavaScript logging
+    debug_mode = traitlets.Bool(
+        default_value=False, help="Enable or disable JavaScript console logging"
+    ).tag(sync=True)
+
+    # Camera synchronization callbacks
+    camera_sync_enabled = traitlets.Bool(
+        default_value=False,
+        help="Enable or disable camera position synchronization callbacks"
+    ).tag(sync=True)
+
+    # Point picking mode for camera calibration
+    point_picking_mode = traitlets.Bool(
+        default_value=False,
+        help="Enable point picking mode for camera calibration"
+    ).tag(sync=True)
+    
+    point_picking_config = traitlets.Dict(
+        default_value={},
+        help="Configuration for point picking (color, label, etc.)"
+    ).tag(sync=True)
+    
+    picked_points = traitlets.List(
+        trait=traitlets.Dict(),
+        default_value=[],
+        help="List of picked 3D points with coordinates and metadata"
+    ).tag(sync=True)
+    
+    point_picking_event = traitlets.Dict(
+        default_value={},
+        help="Last picked point event (triggered on each pick)"
     ).tag(sync=True)
 
     def __init__(self, **kwargs):
@@ -141,14 +215,12 @@ class CesiumWidget(anywidget.AnyWidget):
             if env_token:
                 kwargs["ion_access_token"] = env_token
             else:
-                print("⚠️  No Cesium Ion access token provided.")
-                print(
-                    "   Your access token can be found at: https://ion.cesium.com/tokens"
-                )
-                print("   You can set it via:")
-                print("   - CesiumWidget(ion_access_token='your_token')")
-                print("   - export CESIUM_ION_TOKEN='your_token'  # in your shell")
-                print("   Note: Some features may not work without a token.")
+                logger.warning("No Cesium Ion access token provided.")
+                logger.warning("Your access token can be found at: https://ion.cesium.com/tokens")
+                logger.warning("You can set it via:")
+                logger.warning("  - CesiumWidget(ion_access_token='your_token')")
+                logger.warning("  - export CESIUM_ION_TOKEN='your_token'  # in your shell")
+                logger.warning("Note: Some features may not work without a token.")
 
         super().__init__(**kwargs)
 
@@ -202,7 +274,8 @@ class CesiumWidget(anywidget.AnyWidget):
 
     def set_view(
         self, latitude: float, longitude: float, altitude: float = 400, 
-        heading: float = 0.0, pitch: float = -15.0, roll: float = 0.0
+        heading: float = 0.0, pitch: float = -15.0, roll: float = 0.0,
+        fov: float = None, aspect_ratio: float = None, near: float = None, far: float = None
     ):
         """Set the camera view instantly without animation.
 
@@ -220,11 +293,24 @@ class CesiumWidget(anywidget.AnyWidget):
             Camera pitch in degrees (default: -15.0)
         roll : float, optional
             Camera roll in degrees (default: 0.0)
+        fov : float, optional
+            Field of view in degrees. If provided, sets the camera frustum's vertical
+            field of view (for PerspectiveFrustum). Default is None (uses camera default).
+        aspect_ratio : float, optional
+            Aspect ratio (width/height) of the frustum. If provided, sets the camera
+            frustum's aspect ratio. Default is None (uses camera default).
+        near : float, optional
+            Near clipping plane distance in meters. If provided, sets the camera
+            frustum's near plane. Default is None (uses camera default).
+        far : float, optional
+            Far clipping plane distance in meters. If provided, sets the camera
+            frustum's far plane. Default is None (uses camera default).
             
         Examples
         --------
         >>> widget.set_view(48.8566, 2.3522, altitude=1000)
         >>> widget.set_view(40.7128, -74.0060, heading=90, pitch=-45)
+        >>> widget.set_view(46.3712, 4.6355, altitude=310, fov=60, aspect_ratio=1.5)
         """
         import time
         # Update traitlets for state sync
@@ -235,7 +321,7 @@ class CesiumWidget(anywidget.AnyWidget):
         self.pitch = pitch
         self.roll = roll
         # Send command for instant view change
-        self.camera_command = {
+        camera_cmd = {
             'command': 'setView',
             'latitude': latitude,
             'longitude': longitude,
@@ -245,6 +331,16 @@ class CesiumWidget(anywidget.AnyWidget):
             'roll': roll,
             'timestamp': time.time()
         }
+        # Add optional frustum parameters if provided
+        if fov is not None:
+            camera_cmd['fov'] = fov
+        if aspect_ratio is not None:
+            camera_cmd['aspectRatio'] = aspect_ratio
+        if near is not None:
+            camera_cmd['near'] = near
+        if far is not None:
+            camera_cmd['far'] = far
+        self.camera_command = camera_cmd
 
     def look_at(self, target_latitude: float, target_longitude: float, target_altitude: float = 0,
                 offset_heading: float = 0.0, offset_pitch: float = -45.0, offset_range: float = 1000.0):
@@ -561,6 +657,104 @@ class CesiumWidget(anywidget.AnyWidget):
         if roll is not None:
             self.roll = roll
 
+    def set_camera_from_frustum(self, frustum):
+        """Set camera parameters from a CameraFrustum object.
+        
+        This is a convenience method for setting the camera to match a frustum's
+        position and orientation.
+
+        Parameters
+        ----------
+        frustum : CameraFrustum
+            A CameraFrustum object from frustum_czml module containing position
+            and orientation information.
+            
+        Examples
+        --------
+        >>> from examples.photo_projection.frustum_czml import CameraFrustum, Position, Orientation
+        >>> position = Position.from_cartographic(longitude=-74.0060, latitude=40.7128, altitude=500)
+        >>> orientation = Orientation(heading=45, pitch=-30, roll=0)
+        >>> frustum = CameraFrustum(
+        ...     id="my_frustum",
+        ...     name="My Camera",
+        ...     position=position,
+        ...     orientation=orientation,
+        ...     fov_horizontal=60
+        ... )
+        >>> widget.set_camera_from_frustum(frustum)
+        
+        See Also
+        --------
+        set_camera : Set individual camera parameters
+        """
+        # Extract position (convert to cartographic if needed)
+        lon, lat, alt = frustum.position.to_cartographic()
+        
+        # Set camera with frustum's position and orientation
+        self.set_camera(
+            latitude=lat,
+            longitude=lon,
+            altitude=alt,
+            heading=frustum.orientation.heading,
+            pitch=frustum.orientation.pitch,
+            roll=frustum.orientation.roll
+        )
+
+    def enable_photorealistic_3d_tiles(self, enabled: bool = True):
+        """Enable or disable Google Photorealistic 3D Tiles.
+        
+        This is a convenience method that automatically configures the widget
+        with recommended settings for photorealistic tiles.
+        
+        When enabled (True):
+        - Activates Google Photorealistic 3D Tiles (global photorealistic base layer)
+        - Disables the base globe (recommended to avoid rendering conflicts)
+        - Disables terrain (tiles include 3D terrain data)
+        
+        When disabled (False):
+        - Deactivates photorealistic tiles
+        - Re-enables the base globe
+        - Re-enables terrain
+        
+        Parameters
+        ----------
+        enabled : bool, optional
+            Whether to enable (True) or disable (False) photorealistic tiles (default: True)
+            
+        Examples
+        --------
+        >>> widget = CesiumWidget()
+        >>> widget.enable_photorealistic_3d_tiles(True)
+        >>> # Fly to a location to see the photorealistic tiles
+        >>> widget.fly_to(latitude=40.7128, longitude=-74.0060, altitude=2000)
+        
+        >>> # Disable photorealistic tiles and return to standard globe
+        >>> widget.enable_photorealistic_3d_tiles(False)
+        
+        Notes
+        -----
+        - Photorealistic 3D Tiles require a valid Cesium Ion access token
+        - Coverage is available for major cities and populated areas globally
+        - Performance may vary based on your hardware and network connection
+        - Use the geocoder (magnifying glass icon) to search for locations
+        
+        See Also
+        --------
+        fly_to : Fly the camera to a specific location
+        set_view : Set the camera view instantly
+        
+        References
+        ----------
+        - CesiumJS Photorealistic 3D Tiles Tutorial: 
+          https://cesium.com/learn/cesiumjs-learn/cesiumjs-photorealistic-3d-tiles/
+        - Google Photorealistic 3D Tiles Documentation:
+          https://cesium.com/platform/cesium-ion/content/google-photorealistic-3d-tiles/
+        """
+        self.enable_photorealistic_tiles = enabled
+        self.show_globe = not enabled
+        if enabled:
+            self.enable_terrain = False
+
     def load_geojson(self, geojson, append=False):
         """Load GeoJSON data for visualization.
 
@@ -670,6 +864,47 @@ class CesiumWidget(anywidget.AnyWidget):
         """
         self.czml_data = []
 
+    def update_czml_entity(self, entity_id: str, properties: dict):
+        """Update properties of an existing CZML entity.
+        
+        This method allows you to dynamically update properties of CZML entities
+        without reloading the entire data source. Useful for interactive sliders.
+        
+        Parameters
+        ----------
+        entity_id : str
+            The ID of the entity to update
+        properties : dict
+            Dictionary of properties to update. Supports:
+            - orientation: dict with heading, pitch, roll (in degrees)
+            - position: dict with latitude, longitude, altitude
+            - Any other CZML property that can be updated
+            
+        Examples
+        --------
+        Update orientation:
+        >>> widget.update_czml_entity('photo1', {
+        ...     'orientation': {'heading': 45, 'pitch': -30, 'roll': 0}
+        ... })
+        
+        Update position:
+        >>> widget.update_czml_entity('photo1', {
+        ...     'position': {'latitude': 40.7128, 'longitude': -74.0060, 'altitude': 100}
+        ... })
+        
+        Update multiple properties:
+        >>> widget.update_czml_entity('photo1', {
+        ...     'orientation': {'heading': 90, 'pitch': -15, 'roll': 5},
+        ...     'position': {'latitude': 40.7128, 'longitude': -74.0060, 'altitude': 150}
+        ... })
+        """
+        import time
+        self.czml_entity_update = {
+            'entity_id': entity_id,
+            'properties': properties,
+            'timestamp': time.time()
+        }
+
     def enable_measurement(self, mode: str = "distance"):
         """Enable a measurement tool.
 
@@ -774,6 +1009,59 @@ class CesiumWidget(anywidget.AnyWidget):
         """Hide the measurements list panel."""
         self.show_measurements_list = False
 
+    def enable_debug(self):
+        """Enable JavaScript console logging for debugging.
+        
+        When enabled, detailed logs will be printed to the browser console
+        showing widget initialization, data loading, camera events, etc.
+        
+        Examples
+        --------
+        >>> widget.enable_debug()  # Enable logging
+        >>> # ... interact with widget, check browser console for logs
+        >>> widget.disable_debug()  # Disable logging when done
+        """
+        self.debug_mode = True
+
+    def disable_debug(self):
+        """Disable JavaScript console logging.
+        
+        Examples
+        --------
+        >>> widget.disable_debug()
+        """
+        self.debug_mode = False
+
+    def enable_camera_sync(self):
+        """Enable camera synchronization callbacks.
+        
+        When enabled, camera position changes in the Cesium viewer will be
+        synchronized back to the Python model (latitude, longitude, altitude,
+        heading, pitch, roll properties).
+        
+        Note: This is disabled by default to avoid unnecessary updates when
+        you don't need to track camera position in Python.
+        
+        Examples
+        --------
+        >>> widget.enable_camera_sync()
+        >>> # Move camera in the viewer...
+        >>> print(widget.latitude, widget.longitude)  # Updated values
+        """
+        self.camera_sync_enabled = True
+
+    def disable_camera_sync(self):
+        """Disable camera synchronization callbacks.
+        
+        When disabled, camera movements in the viewer will not update the
+        Python model properties. This is the default state.
+        
+        Examples
+        --------
+        >>> widget.disable_camera_sync()
+        """
+        self.camera_sync_enabled = False
+
     def set_atmosphere(self, 
                       brightness_shift=None, 
                       hue_shift=None, 
@@ -1011,9 +1299,12 @@ class CesiumWidget(anywidget.AnyWidget):
         clicks, timeline scrubbing, etc.) with a dictionary containing:
         
         - type: Interaction type ('camera_move', 'left_click', 'right_click', 'timeline_scrub')
-        - timestamp: ISO 8601 timestamp when interaction occurred
+        - timestamp: ISO 8601 timestamp when interaction occurred (system time)
         - camera: Camera state (latitude, longitude, altitude, heading, pitch, roll)
-        - clock: Clock state (current_time, multiplier, is_animating) if timeline enabled
+        - clock: Cesium clock state with:
+            - current_time: ISO 8601 timestamp from Cesium's clock (simulation time)
+            - multiplier: Clock speed multiplier
+            - is_animating: Whether clock is currently animating
         - picked_position: Coordinates of clicked location (if applicable)
         - picked_entity: Information about clicked entity (if applicable)
         
@@ -1027,6 +1318,8 @@ class CesiumWidget(anywidget.AnyWidget):
         >>> def handle_interaction(event):
         ...     print(f"Interaction: {event['type']}")
         ...     print(f"Camera at: {event['camera']['latitude']}, {event['camera']['longitude']}")
+        ...     if event['clock']:
+        ...         print(f"Cesium time: {event['clock']['current_time']}")
         ...     if 'picked_position' in event:
         ...         print(f"Clicked: {event['picked_position']}")
         >>> 
@@ -1045,43 +1338,324 @@ class CesiumWidget(anywidget.AnyWidget):
 
         This is useful for troubleshooting widget initialization issues.
         """
-        print("=== CesiumWidget Debug Info ===")
-        print(f"Widget class: {self.__class__.__name__}")
-        print(f"Anywidget version: {anywidget.__version__}")
+        def emit(message: str, *args):
+            line = message % args if args else message
+            print(line)
+            logger.info(message, *args)
+
+        emit("=== CesiumWidget Debug Info ===")
+        emit("Widget class: %s", self.__class__.__name__)
+        emit("Anywidget version: %s", anywidget.__version__)
 
         # Check file paths (note: after widget instantiation, _esm and _css contain file contents)
         esm_path = pathlib.Path(__file__).parent / "index.js"
         css_path = pathlib.Path(__file__).parent / "styles.css"
 
-        print("\nJavaScript file:")
-        print(f"  Path: {esm_path}")
-        print(f"  Exists: {esm_path.exists()}")
+        emit("JavaScript file:")
+        emit("  Path: %s", esm_path)
+        emit("  Exists: %s", esm_path.exists())
         if esm_path.exists():
-            print(f"  Size: {esm_path.stat().st_size} bytes")
+            emit("  Size: %d bytes", esm_path.stat().st_size)
         elif isinstance(self._esm, str):
-            print(f"  Content loaded: {len(self._esm)} chars")
+            emit("  Content loaded: %d chars", len(self._esm))
 
-        print("\nCSS file:")
-        print(f"  Path: {css_path}")
-        print(f"  Exists: {css_path.exists()}")
+        emit("CSS file:")
+        emit("  Path: %s", css_path)
+        emit("  Exists: %s", css_path.exists())
         if css_path.exists():
-            print(f"  Size: {css_path.stat().st_size} bytes")
+            emit("  Size: %d bytes", css_path.stat().st_size)
         elif isinstance(self._css, str):
-            print(f"  Content loaded: {len(self._css)} chars")
+            emit("  Content loaded: %d chars", len(self._css))
 
         # Show current state
-        print("\nCurrent state:")
-        print(f"  Position: ({self.latitude:.4f}°, {self.longitude:.4f}°)")
-        print(f"  Altitude: {self.altitude:.2f}m")
-        print(f"  Height: {self.height}")
-        print(f"  Terrain: {self.enable_terrain}")
-        print(f"  Lighting: {self.enable_lighting}")
-
-        print("\n💡 Debugging tips:")
-        print("  1. Open browser DevTools (F12) and check the Console tab for errors")
-        print("  2. Check Network tab to see if CesiumJS CDN loads successfully")
-        print(
-            "  3. Try: widget = CesiumWidget(enable_terrain=False) to avoid async terrain loading"
-        )
-        print("  4. Ensure you're using JupyterLab 4.0+ or Jupyter Notebook 7.0+")
-        print("  5. Check if anywidget is properly installed: pip show anywidget")
+        emit("Current state:")
+        emit("  Position: (%.4f°, %.4f°)", self.latitude, self.longitude)
+        emit("  Altitude: %.2fm", self.altitude)
+        emit("  Height: %s", self.height)
+        emit("  Terrain: %s", self.enable_terrain)
+        emit("  Lighting: %s", self.enable_lighting)
+
+        emit("💡 Debugging tips:")
+        emit("  1. Open browser DevTools (F12) and check the Console tab for errors")
+        emit("  2. Check Network tab to see if CesiumJS CDN loads successfully")
+        emit("  3. Try: widget = CesiumWidget(enable_terrain=False) to avoid async terrain loading")
+        emit("  4. Ensure you're using JupyterLab 4.0+ or Jupyter Notebook 7.0+")
+        emit("  5. Check if anywidget is properly installed: pip show anywidget")
+
+    # ============= Point Picking Methods for Camera Calibration =============
+
+    def start_point_picking(
+        self,
+        color: tuple = (255, 0, 0, 255),
+        label_prefix: str = "GCP",
+        point_id_prefix: str = "",
+        continuous: bool = True,
+    ):
+        """Start point picking mode for camera calibration.
+        
+        When enabled, clicking on the 3D scene will record the 3D coordinates
+        of the clicked point. Points are added to the `picked_points` list.
+        
+        Parameters
+        ----------
+        color : tuple, optional
+            RGBA color for the point marker (0-255 each). Default is red.
+        label_prefix : str, optional
+            Prefix for auto-generated labels (e.g., "GCP" -> "GCP_1", "GCP_2", ...)
+            Default is "GCP".
+        point_id_prefix : str, optional
+            Prefix for auto-generated point IDs. If empty, uses label_prefix.
+        continuous : bool, optional
+            If True (default), allows picking multiple points with auto-incrementing IDs.
+            If False, picks only one point and then stops.
+            
+        Examples
+        --------
+        Pick multiple points (default):
+        >>> widget.start_point_picking(label_prefix="GCP")
+        >>> # Click multiple times on the scene to pick points
+        >>> # Points will be labeled GCP_1, GCP_2, GCP_3, etc.
+        >>> widget.stop_point_picking()
+        >>> print(widget.picked_points)
+        
+        Pick a single point:
+        >>> widget.start_point_picking(label_prefix="P1", continuous=False)
+        >>> # Click once - picking stops automatically
+        """
+        import time
+        
+        if not point_id_prefix:
+            point_id_prefix = label_prefix
+        
+        self.point_picking_config = {
+            'color': list(color),
+            'label_prefix': label_prefix,
+            'point_id_prefix': point_id_prefix,
+            'continuous': continuous,
+            'timestamp': time.time(),
+        }
+        self.point_picking_mode = True
+        
+        mode_desc = "continuous" if continuous else "single-point"
+        logger.info("🎯 Point picking mode enabled (%s). Click on the 3D scene to pick points.", mode_desc)
+        logger.info("   Points will be labeled: %s_1, %s_2, ...", label_prefix, label_prefix)
+        logger.info("   Call widget.stop_point_picking() when done.")
+
+    def stop_point_picking(self):
+        """Stop point picking mode.
+        
+        Examples
+        --------
+        >>> widget.stop_point_picking()
+        """
+        self.point_picking_mode = False
+        self.point_picking_config = {}
+        logger.info("🛑 Point picking mode disabled.")
+
+    def clear_picked_points(self):
+        """Clear all picked points.
+        
+        This removes all picked points from the list and their visual markers
+        from the 3D scene.
+        
+        Examples
+        --------
+        >>> widget.clear_picked_points()
+        """
+        self.picked_points = []
+        logger.info("🗑️  Cleared all picked points.")
+
+    def remove_picked_point(self, point_id: str):
+        """Remove a specific picked point by its ID.
+        
+        Parameters
+        ----------
+        point_id : str
+            The ID of the point to remove
+            
+        Examples
+        --------
+        >>> widget.remove_picked_point("P1")
+        """
+        current_points = list(self.picked_points)
+        self.picked_points = [p for p in current_points if p.get('id') != point_id]
+        logger.info("🗑️  Removed point %s.", point_id)
+
+    def on_point_picked(self, callback):
+        """Register a callback for point picking events.
+        
+        The callback will be called each time a point is picked in the 3D scene.
+        
+        Parameters
+        ----------
+        callback : callable
+            Function to call with picked point data:
+            callback({'id': str, 'latitude': float, 'longitude': float, 
+                     'altitude_wgs84': float, 'altitude_msl': float,
+                     'color': list, 'label': str})
+            
+        Returns
+        -------
+        callable
+            The wrapper function (can be used to unobserve)
+            
+        Examples
+        --------
+        >>> def handle_pick(point):
+        ...     print(f"Picked {point['id']} at {point['latitude']}, {point['longitude']}")
+        >>> 
+        >>> widget.on_point_picked(handle_pick)
+        """
+        def wrapper(change):
+            event_data = change['new']
+            if event_data and event_data.get('id'):
+                callback(event_data)
+        
+        self.observe(wrapper, names='point_picking_event')
+        return wrapper
+
+    # ============= Clock/Timeline Control Methods =============
+
+    def set_time(self, time):
+        """Set the current time on the Cesium timeline.
+
+        Parameters
+        ----------
+        time : str or datetime
+            Time to set. Can be:
+            - ISO 8601 string (e.g., '2023-08-01T14:30:00Z')
+            - datetime object (will be converted to ISO 8601)
+
+        Examples
+        --------
+        >>> from datetime import datetime
+        >>> widget.set_time('2023-08-01T14:30:00Z')
+        >>> widget.set_time(datetime(2023, 8, 1, 14, 30))
+        """
+        from datetime import datetime as dt
+        
+        if isinstance(time, dt):
+            time_str = time.isoformat() + 'Z'
+        else:
+            time_str = str(time)
+        
+        self.current_time = time_str
+        self.clock_command = {
+            'command': 'setTime',
+            'time': time_str,
+            'timestamp': __import__('time').time()
+        }
+
+    def play(self):
+        """Start the timeline animation.
+
+        Examples
+        --------
+        >>> widget.play()
+        """
+        self.should_animate = True
+        self.clock_command = {
+            'command': 'play',
+            'timestamp': __import__('time').time()
+        }
+
+    def pause(self):
+        """Pause the timeline animation.
+
+        Examples
+        --------
+        >>> widget.pause()
+        """
+        self.should_animate = False
+        self.clock_command = {
+            'command': 'pause',
+            'timestamp': __import__('time').time()
+        }
+
+    def set_speed(self, multiplier: float = 1.0):
+        """Set the animation speed multiplier.
+
+        Parameters
+        ----------
+        multiplier : float, optional
+            Speed multiplier (default: 1.0)
+            - 1.0 = real-time
+            - 60.0 = 60x speed (1 second = 1 minute)
+            - 0.5 = half speed
+
+        Examples
+        --------
+        >>> widget.set_speed(60)  # 60x speed
+        >>> widget.set_speed(0.5)  # Half speed
+        """
+        self.clock_multiplier = multiplier
+        self.clock_command = {
+            'command': 'setMultiplier',
+            'multiplier': multiplier,
+            'timestamp': __import__('time').time()
+        }
+
+    def set_clock_range(self, start_time, stop_time):
+        """Set the time range for the clock/timeline.
+
+        Parameters
+        ----------
+        start_time : str or datetime
+            Start time of the range
+        stop_time : str or datetime
+            Stop time of the range
+
+        Examples
+        --------
+        >>> from datetime import datetime
+        >>> widget.set_clock_range(
+        ...     datetime(2023, 8, 1, 0, 0),
+        ...     datetime(2023, 8, 2, 0, 0)
+        ... )
+        """
+        from datetime import datetime as dt
+        
+        if isinstance(start_time, dt):
+            start_str = start_time.isoformat() + 'Z'
+        else:
+            start_str = str(start_time)
+            
+        if isinstance(stop_time, dt):
+            stop_str = stop_time.isoformat() + 'Z'
+        else:
+            stop_str = str(stop_time)
+        
+        self.clock_command = {
+            'command': 'setRange',
+            'startTime': start_str,
+            'stopTime': stop_str,
+            'timestamp': __import__('time').time()
+        }
+
+    def get_picked_points_as_correspondences(self):
+        """Convert picked points to CorrespondencePoint objects.
+        
+        This is useful for camera calibration workflows where you need
+        to combine 2D photo points with 3D scene points.
+        
+        Returns
+        -------
+        list
+            List of dictionaries with point data ready for camera calibration
+            
+        Examples
+        --------
+        >>> points_3d = widget.get_picked_points_as_correspondences()
+        >>> # Combine with 2D points from photo selector
+        """
+        return [
+            {
+                'id': p.get('id', f"point_{i}"),
+                'latitude': p.get('latitude'),
+                'longitude': p.get('longitude'),
+                'altitude_msl': p.get('altitude_msl'),
+                'color': tuple(p.get('color', [255, 0, 0, 255])),
+                'description': p.get('label', ''),
+            }
+            for i, p in enumerate(self.picked_points)
+        ]