cesiumjs-anywidget 0.2.4__py3-none-any.whl → 0.3.0__py3-none-any.whl

cesiumjs_anywidget/index.js

@@ -85,64 +85,318 @@ function setupViewerListeners(viewer, model, container, Cesium) {
       return;
     viewer.animation.container.style.visibility = model.get("show_animation") ? "visible" : "hidden";
   });
+  model.on("change:atmosphere_settings", () => {
+    if (!viewer || !viewer.scene || !viewer.scene.atmosphere)
+      return;
+    const settings = model.get("atmosphere_settings");
+    if (!settings || Object.keys(settings).length === 0)
+      return;
+    const atmosphere = viewer.scene.atmosphere;
+    if (settings.brightnessShift !== void 0) {
+      atmosphere.brightnessShift = settings.brightnessShift;
+    }
+    if (settings.hueShift !== void 0) {
+      atmosphere.hueShift = settings.hueShift;
+    }
+    if (settings.saturationShift !== void 0) {
+      atmosphere.saturationShift = settings.saturationShift;
+    }
+    if (settings.lightIntensity !== void 0) {
+      atmosphere.lightIntensity = settings.lightIntensity;
+    }
+    if (settings.rayleighCoefficient !== void 0 && Array.isArray(settings.rayleighCoefficient) && settings.rayleighCoefficient.length === 3) {
+      atmosphere.rayleighCoefficient = new Cesium.Cartesian3(
+        settings.rayleighCoefficient[0],
+        settings.rayleighCoefficient[1],
+        settings.rayleighCoefficient[2]
+      );
+    }
+    if (settings.rayleighScaleHeight !== void 0) {
+      atmosphere.rayleighScaleHeight = settings.rayleighScaleHeight;
+    }
+    if (settings.mieCoefficient !== void 0 && Array.isArray(settings.mieCoefficient) && settings.mieCoefficient.length === 3) {
+      atmosphere.mieCoefficient = new Cesium.Cartesian3(
+        settings.mieCoefficient[0],
+        settings.mieCoefficient[1],
+        settings.mieCoefficient[2]
+      );
+    }
+    if (settings.mieScaleHeight !== void 0) {
+      atmosphere.mieScaleHeight = settings.mieScaleHeight;
+    }
+    if (settings.mieAnisotropy !== void 0) {
+      atmosphere.mieAnisotropy = settings.mieAnisotropy;
+    }
+  });
+  model.on("change:sky_atmosphere_settings", () => {
+    if (!viewer || !viewer.scene || !viewer.scene.skyAtmosphere)
+      return;
+    const settings = model.get("sky_atmosphere_settings");
+    if (!settings || Object.keys(settings).length === 0)
+      return;
+    const skyAtmosphere = viewer.scene.skyAtmosphere;
+    if (settings.show !== void 0) {
+      skyAtmosphere.show = settings.show;
+    }
+    if (settings.brightnessShift !== void 0) {
+      skyAtmosphere.brightnessShift = settings.brightnessShift;
+    }
+    if (settings.hueShift !== void 0) {
+      skyAtmosphere.hueShift = settings.hueShift;
+    }
+    if (settings.saturationShift !== void 0) {
+      skyAtmosphere.saturationShift = settings.saturationShift;
+    }
+    if (settings.atmosphereLightIntensity !== void 0) {
+      skyAtmosphere.atmosphereLightIntensity = settings.atmosphereLightIntensity;
+    }
+    if (settings.atmosphereRayleighCoefficient !== void 0 && Array.isArray(settings.atmosphereRayleighCoefficient) && settings.atmosphereRayleighCoefficient.length === 3) {
+      skyAtmosphere.atmosphereRayleighCoefficient = new Cesium.Cartesian3(
+        settings.atmosphereRayleighCoefficient[0],
+        settings.atmosphereRayleighCoefficient[1],
+        settings.atmosphereRayleighCoefficient[2]
+      );
+    }
+    if (settings.atmosphereRayleighScaleHeight !== void 0) {
+      skyAtmosphere.atmosphereRayleighScaleHeight = settings.atmosphereRayleighScaleHeight;
+    }
+    if (settings.atmosphereMieCoefficient !== void 0 && Array.isArray(settings.atmosphereMieCoefficient) && settings.atmosphereMieCoefficient.length === 3) {
+      skyAtmosphere.atmosphereMieCoefficient = new Cesium.Cartesian3(
+        settings.atmosphereMieCoefficient[0],
+        settings.atmosphereMieCoefficient[1],
+        settings.atmosphereMieCoefficient[2]
+      );
+    }
+    if (settings.atmosphereMieScaleHeight !== void 0) {
+      skyAtmosphere.atmosphereMieScaleHeight = settings.atmosphereMieScaleHeight;
+    }
+    if (settings.atmosphereMieAnisotropy !== void 0) {
+      skyAtmosphere.atmosphereMieAnisotropy = settings.atmosphereMieAnisotropy;
+    }
+    if (settings.perFragmentAtmosphere !== void 0) {
+      skyAtmosphere.perFragmentAtmosphere = settings.perFragmentAtmosphere;
+    }
+  });
+  model.on("change:skybox_settings", () => {
+    if (!viewer || !viewer.scene || !viewer.scene.skyBox)
+      return;
+    const settings = model.get("skybox_settings");
+    if (!settings || Object.keys(settings).length === 0)
+      return;
+    const skyBox = viewer.scene.skyBox;
+    if (settings.show !== void 0) {
+      skyBox.show = settings.show;
+    }
+    if (settings.sources !== void 0 && settings.sources !== null) {
+      const sources = settings.sources;
+      if (sources.positiveX && sources.negativeX && sources.positiveY && sources.negativeY && sources.positiveZ && sources.negativeZ) {
+        viewer.scene.skyBox = new Cesium.SkyBox({
+          sources: {
+            positiveX: sources.positiveX,
+            negativeX: sources.negativeX,
+            positiveY: sources.positiveY,
+            negativeY: sources.negativeY,
+            positiveZ: sources.positiveZ,
+            negativeZ: sources.negativeZ
+          }
+        });
+        if (settings.show !== void 0) {
+          viewer.scene.skyBox.show = settings.show;
+        }
+      }
+    }
+  });
+  function getCameraState() {
+    const cartographic = viewer.camera.positionCartographic;
+    return {
+      latitude: Cesium.Math.toDegrees(cartographic.latitude),
+      longitude: Cesium.Math.toDegrees(cartographic.longitude),
+      altitude: cartographic.height,
+      heading: Cesium.Math.toDegrees(viewer.camera.heading),
+      pitch: Cesium.Math.toDegrees(viewer.camera.pitch),
+      roll: Cesium.Math.toDegrees(viewer.camera.roll)
+    };
+  }
+  function getClockState() {
+    if (!viewer.clock)
+      return null;
+    return {
+      current_time: Cesium.JulianDate.toIso8601(viewer.clock.currentTime),
+      multiplier: viewer.clock.multiplier,
+      is_animating: viewer.clock.shouldAnimate
+    };
+  }
+  function sendInteractionEvent(type, additionalData = {}) {
+    const event = {
+      type,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      camera: getCameraState(),
+      clock: getClockState(),
+      ...additionalData
+    };
+    console.log("[CesiumWidget] Interaction event:", type, event);
+    model.set("interaction_event", event);
+    model.save_changes();
+  }
+  const camera = viewer.camera;
+  camera.moveEnd.addEventListener(() => {
+    sendInteractionEvent("camera_move");
+  });
+  const scene = viewer.scene;
+  const handler = new Cesium.ScreenSpaceEventHandler(scene.canvas);
+  handler.setInputAction((click) => {
+    const pickedData = {};
+    const ray = viewer.camera.getPickRay(click.position);
+    const cartesian = viewer.scene.globe.pick(ray, viewer.scene);
+    if (cartesian) {
+      const cartographic = Cesium.Cartographic.fromCartesian(cartesian);
+      pickedData.picked_position = {
+        latitude: Cesium.Math.toDegrees(cartographic.latitude),
+        longitude: Cesium.Math.toDegrees(cartographic.longitude),
+        altitude: cartographic.height
+      };
+    }
+    const pickedObject = viewer.scene.pick(click.position);
+    if (Cesium.defined(pickedObject) && Cesium.defined(pickedObject.id)) {
+      const entity = pickedObject.id;
+      pickedData.picked_entity = {
+        id: entity.id,
+        name: entity.name || null
+      };
+      if (entity.properties) {
+        const props = {};
+        const propertyNames = entity.properties.propertyNames;
+        if (propertyNames && propertyNames.length > 0) {
+          propertyNames.forEach((name) => {
+            try {
+              props[name] = entity.properties[name].getValue(viewer.clock.currentTime);
+            } catch (e) {
+            }
+          });
+          if (Object.keys(props).length > 0) {
+            pickedData.picked_entity.properties = props;
+          }
+        }
+      }
+    }
+    sendInteractionEvent("left_click", pickedData);
+  }, Cesium.ScreenSpaceEventType.LEFT_CLICK);
+  handler.setInputAction((click) => {
+    const pickedData = {};
+    const ray = viewer.camera.getPickRay(click.position);
+    const cartesian = viewer.scene.globe.pick(ray, viewer.scene);
+    if (cartesian) {
+      const cartographic = Cesium.Cartographic.fromCartesian(cartesian);
+      pickedData.picked_position = {
+        latitude: Cesium.Math.toDegrees(cartographic.latitude),
+        longitude: Cesium.Math.toDegrees(cartographic.longitude),
+        altitude: cartographic.height
+      };
+    }
+    sendInteractionEvent("right_click", pickedData);
+  }, Cesium.ScreenSpaceEventType.RIGHT_CLICK);
+  if (viewer.timeline) {
+    let timelineScrubbing = false;
+    let scrubTimeout = null;
+    viewer.clock.onTick.addEventListener(() => {
+      if (viewer.timeline) {
+        if (scrubTimeout) {
+          clearTimeout(scrubTimeout);
+        }
+        scrubTimeout = setTimeout(() => {
+          if (timelineScrubbing) {
+            timelineScrubbing = false;
+            sendInteractionEvent("timeline_scrub");
+          }
+        }, 500);
+        timelineScrubbing = true;
+      }
+    });
+  }
 }
 function setupGeoJSONLoader(viewer, model, Cesium) {
-  let geojsonDataSource = null;
+  let geojsonDataSources = [];
   model.on("change:geojson_data", async () => {
-    if (!viewer)
+    if (!viewer || !viewer.dataSources)
       return;
-    const geojsonData = model.get("geojson_data");
-    if (geojsonDataSource) {
-      viewer.dataSources.remove(geojsonDataSource);
-      geojsonDataSource = null;
-    }
-    if (geojsonData) {
-      try {
-        geojsonDataSource = await Cesium.GeoJsonDataSource.load(geojsonData, {
-          stroke: Cesium.Color.HOTPINK,
-          fill: Cesium.Color.PINK.withAlpha(0.5),
-          strokeWidth: 3
-        });
-        viewer.dataSources.add(geojsonDataSource);
-        viewer.flyTo(geojsonDataSource);
-      } catch (error) {
-        console.error("Error loading GeoJSON:", error);
+    const geojsonDataArray = model.get("geojson_data");
+    geojsonDataSources.forEach((dataSource) => {
+      if (viewer && viewer.dataSources) {
+        viewer.dataSources.remove(dataSource);
+      }
+    });
+    geojsonDataSources = [];
+    if (geojsonDataArray && Array.isArray(geojsonDataArray)) {
+      for (const geojsonData of geojsonDataArray) {
+        try {
+          const dataSource = await Cesium.GeoJsonDataSource.load(geojsonData, {
+            stroke: Cesium.Color.HOTPINK,
+            fill: Cesium.Color.PINK.withAlpha(0.5),
+            strokeWidth: 3
+          });
+          if (viewer && viewer.dataSources) {
+            viewer.dataSources.add(dataSource);
+            geojsonDataSources.push(dataSource);
+          }
+        } catch (error) {
+          console.error("Error loading GeoJSON:", error);
+        }
+      }
+      if (geojsonDataSources.length > 0 && viewer && viewer.flyTo) {
+        viewer.flyTo(geojsonDataSources[0]);
       }
     }
   });
   return {
     destroy: () => {
-      if (geojsonDataSource && viewer) {
-        viewer.dataSources.remove(geojsonDataSource);
-      }
+      geojsonDataSources.forEach((dataSource) => {
+        if (viewer) {
+          viewer.dataSources.remove(dataSource);
+        }
+      });
+      geojsonDataSources = [];
     }
   };
 }
 function setupCZMLLoader(viewer, model, Cesium) {
-  let czmlDataSource = null;
+  let czmlDataSources = [];
   model.on("change:czml_data", async () => {
-    if (!viewer)
+    if (!viewer || !viewer.dataSources)
       return;
-    const czmlData = model.get("czml_data");
-    if (czmlDataSource) {
-      viewer.dataSources.remove(czmlDataSource);
-      czmlDataSource = null;
-    }
-    if (czmlData && Array.isArray(czmlData) && czmlData.length > 0) {
-      try {
-        czmlDataSource = await Cesium.CzmlDataSource.load(czmlData);
-        viewer.dataSources.add(czmlDataSource);
-        viewer.flyTo(czmlDataSource);
-      } catch (error) {
-        console.error("Error loading CZML:", error);
+    const czmlDataArray = model.get("czml_data");
+    czmlDataSources.forEach((dataSource) => {
+      if (viewer && viewer.dataSources) {
+        viewer.dataSources.remove(dataSource);
+      }
+    });
+    czmlDataSources = [];
+    if (czmlDataArray && Array.isArray(czmlDataArray)) {
+      for (const czmlData of czmlDataArray) {
+        if (Array.isArray(czmlData) && czmlData.length > 0) {
+          try {
+            const dataSource = await Cesium.CzmlDataSource.load(czmlData);
+            if (viewer && viewer.dataSources) {
+              viewer.dataSources.add(dataSource);
+              czmlDataSources.push(dataSource);
+            }
+          } catch (error) {
+            console.error("Error loading CZML:", error);
+          }
+        }
+      }
+      if (czmlDataSources.length > 0 && viewer && viewer.flyTo) {
+        viewer.flyTo(czmlDataSources[0]);
       }
     }
   });
   return {
     destroy: () => {
-      if (czmlDataSource && viewer) {
-        viewer.dataSources.remove(czmlDataSource);
-      }
+      czmlDataSources.forEach((dataSource) => {
+        if (viewer) {
+          viewer.dataSources.remove(dataSource);
+        }
+      });
+      czmlDataSources = [];
     }
   };
 }
@@ -194,6 +448,99 @@ function initializeCameraSync(viewer, model) {
   model.on("change:heading", updateCameraFromModel);
   model.on("change:pitch", updateCameraFromModel);
   model.on("change:roll", updateCameraFromModel);
+  model.on("change:camera_command", () => {
+    const command = model.get("camera_command");
+    if (!command || !command.command || !command.timestamp)
+      return;
+    const cmd = command.command;
+    try {
+      switch (cmd) {
+        case "flyTo":
+          viewer.camera.flyTo({
+            destination: Cesium.Cartesian3.fromDegrees(
+              command.longitude,
+              command.latitude,
+              command.altitude
+            ),
+            orientation: {
+              heading: Cesium.Math.toRadians(command.heading || 0),
+              pitch: Cesium.Math.toRadians(command.pitch || -15),
+              roll: Cesium.Math.toRadians(command.roll || 0)
+            },
+            duration: command.duration || 3
+          });
+          break;
+        case "setView":
+          viewer.camera.setView({
+            destination: Cesium.Cartesian3.fromDegrees(
+              command.longitude,
+              command.latitude,
+              command.altitude
+            ),
+            orientation: {
+              heading: Cesium.Math.toRadians(command.heading || 0),
+              pitch: Cesium.Math.toRadians(command.pitch || -15),
+              roll: Cesium.Math.toRadians(command.roll || 0)
+            }
+          });
+          break;
+        case "lookAt":
+          const target = Cesium.Cartesian3.fromDegrees(
+            command.targetLongitude,
+            command.targetLatitude,
+            command.targetAltitude || 0
+          );
+          const offset = new Cesium.HeadingPitchRange(
+            Cesium.Math.toRadians(command.offsetHeading || 0),
+            Cesium.Math.toRadians(command.offsetPitch || -45),
+            command.offsetRange || 1e3
+          );
+          viewer.camera.lookAt(target, offset);
+          viewer.camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
+          break;
+        case "moveForward":
+          viewer.camera.moveForward(command.distance || 100);
+          break;
+        case "moveBackward":
+          viewer.camera.moveBackward(command.distance || 100);
+          break;
+        case "moveUp":
+          viewer.camera.moveUp(command.distance || 100);
+          break;
+        case "moveDown":
+          viewer.camera.moveDown(command.distance || 100);
+          break;
+        case "moveLeft":
+          viewer.camera.moveLeft(command.distance || 100);
+          break;
+        case "moveRight":
+          viewer.camera.moveRight(command.distance || 100);
+          break;
+        case "rotateLeft":
+          viewer.camera.rotateLeft(Cesium.Math.toRadians(command.angle || 15));
+          break;
+        case "rotateRight":
+          viewer.camera.rotateRight(Cesium.Math.toRadians(command.angle || 15));
+          break;
+        case "rotateUp":
+          viewer.camera.rotateUp(Cesium.Math.toRadians(command.angle || 15));
+          break;
+        case "rotateDown":
+          viewer.camera.rotateDown(Cesium.Math.toRadians(command.angle || 15));
+          break;
+        case "zoomIn":
+          viewer.camera.zoomIn(command.distance || 100);
+          break;
+        case "zoomOut":
+          viewer.camera.zoomOut(command.distance || 100);
+          break;
+        default:
+          console.warn(`Unknown camera command: ${cmd}`);
+      }
+    } catch (error) {
+      console.error(`Error executing camera command ${cmd}:`, error);
+    }
+  });
   return {
     updateCameraFromModel,
     updateModelFromCamera,

cesiumjs_anywidget/widget.py

@@ -65,17 +65,48 @@ class CesiumWidget(anywidget.AnyWidget):
         sync=True
     )
 
-    # GeoJSON data for visualization
-    geojson_data = traitlets.Dict(
-        default_value=None, allow_none=True, help="GeoJSON data to display"
+    # GeoJSON data for visualization (list of GeoJSON objects)
+    geojson_data = traitlets.List(
+        trait=traitlets.Dict(),
+        default_value=[],
+        help="List of GeoJSON datasets to display"
     ).tag(sync=True)
 
-    # CZML data for visualization
+    # CZML data for visualization (list of CZML documents)
     czml_data = traitlets.List(
-        trait=traitlets.Dict(),
-        default_value=None,
-        allow_none=True,
-        help="CZML data to display",
+        trait=traitlets.List(trait=traitlets.Dict()),
+        default_value=[],
+        help="List of CZML documents to display",
+    ).tag(sync=True)
+
+    # Interaction event data - sent when user interaction ends
+    interaction_event = traitlets.Dict(
+        default_value={},
+        help="Interaction event data with camera position, time, and context"
+    ).tag(sync=True)
+
+    # Atmosphere configuration
+    atmosphere_settings = traitlets.Dict(
+        default_value={},
+        help="Atmosphere rendering settings (brightnessShift, hueShift, saturationShift, etc.)"
+    ).tag(sync=True)
+
+    # Sky atmosphere configuration
+    sky_atmosphere_settings = traitlets.Dict(
+        default_value={},
+        help="Sky atmosphere rendering settings (show, brightnessShift, hueShift, etc.)"
+    ).tag(sync=True)
+
+    # SkyBox configuration
+    skybox_settings = traitlets.Dict(
+        default_value={},
+        help="SkyBox rendering settings (show, sources for cube map faces)"
+    ).tag(sync=True)
+
+    # Camera commands (for advanced camera operations)
+    camera_command = traitlets.Dict(
+        default_value={},
+        help="Camera command trigger for flyTo, lookAt, move, rotate, zoom operations"
     ).tag(sync=True)
 
     # Measurement tools
@@ -121,8 +152,10 @@ class CesiumWidget(anywidget.AnyWidget):
 
         super().__init__(**kwargs)
 
-    def fly_to(self, latitude: float, longitude: float, altitude: float = 400, duration: float = 3.0):
-        """Fly the camera to a specific location.
+    def fly_to(self, latitude: float, longitude: float, altitude: float = 400, 
+               heading: float = 0.0, pitch: float = -15.0, roll: float = 0.0,
+               duration: float = 3.0):
+        """Fly the camera to a specific location with animation.
 
         Parameters
         ----------
@@ -132,15 +165,44 @@ class CesiumWidget(anywidget.AnyWidget):
             Target longitude in degrees
         altitude : float, optional
             Target altitude in meters (default: 400)
+        heading : float, optional
+            Camera heading in degrees (default: 0.0)
+        pitch : float, optional
+            Camera pitch in degrees (default: -15.0)
+        roll : float, optional
+            Camera roll in degrees (default: 0.0)
         duration : float, optional
             Flight duration in seconds (default: 3.0)
+            
+        Examples
+        --------
+        >>> widget.fly_to(48.8566, 2.3522, altitude=5000, duration=2.0)
+        >>> widget.fly_to(40.7128, -74.0060, heading=45, pitch=-30)
         """
+        import time
+        # Update traitlets for state sync
         self.latitude = latitude
         self.longitude = longitude
         self.altitude = altitude
+        self.heading = heading
+        self.pitch = pitch
+        self.roll = roll
+        # Send command for animation
+        self.camera_command = {
+            'command': 'flyTo',
+            'latitude': latitude,
+            'longitude': longitude,
+            'altitude': altitude,
+            'heading': heading,
+            'pitch': pitch,
+            'roll': roll,
+            'duration': duration,
+            'timestamp': time.time()
+        }
 
     def set_view(
-        self, latitude : float , longitude: float, altitude: float = 400, heading: float = 0.0, pitch: float = -15.0, roll: float = 0.0
+        self, latitude: float, longitude: float, altitude: float = 400, 
+        heading: float = 0.0, pitch: float = -15.0, roll: float = 0.0
     ):
         """Set the camera view instantly without animation.
 
@@ -158,29 +220,389 @@ class CesiumWidget(anywidget.AnyWidget):
             Camera pitch in degrees (default: -15.0)
         roll : float, optional
             Camera roll in degrees (default: 0.0)
+            
+        Examples
+        --------
+        >>> widget.set_view(48.8566, 2.3522, altitude=1000)
+        >>> widget.set_view(40.7128, -74.0060, heading=90, pitch=-45)
         """
+        import time
+        # Update traitlets for state sync
         self.latitude = latitude
         self.longitude = longitude
         self.altitude = altitude
         self.heading = heading
         self.pitch = pitch
         self.roll = roll
+        # Send command for instant view change
+        self.camera_command = {
+            'command': 'setView',
+            'latitude': latitude,
+            'longitude': longitude,
+            'altitude': altitude,
+            'heading': heading,
+            'pitch': pitch,
+            'roll': roll,
+            'timestamp': time.time()
+        }
+
+    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):
+        """Point the camera at a target location from an offset position.
+        
+        This is useful for looking at a specific point from a certain distance and angle.
+
+        Parameters
+        ----------
+        target_latitude : float
+            Target point latitude in degrees
+        target_longitude : float
+            Target point longitude in degrees
+        target_altitude : float, optional
+            Target point altitude in meters (default: 0)
+        offset_heading : float, optional
+            Heading offset from target in degrees (default: 0.0)
+        offset_pitch : float, optional
+            Pitch offset from target in degrees (default: -45.0)
+        offset_range : float, optional
+            Distance from target in meters (default: 1000.0)
+            
+        Examples
+        --------
+        >>> # Look at Eiffel Tower from 500m away at 30° angle
+        >>> widget.look_at(48.8584, 2.2945, offset_range=500, offset_pitch=-30)
+        
+        >>> # Orbit view around a location
+        >>> widget.look_at(40.7128, -74.0060, offset_heading=45, offset_range=2000)
+        """
+        import time
+        self.camera_command = {
+            'command': 'lookAt',
+            'targetLatitude': target_latitude,
+            'targetLongitude': target_longitude,
+            'targetAltitude': target_altitude,
+            'offsetHeading': offset_heading,
+            'offsetPitch': offset_pitch,
+            'offsetRange': offset_range,
+            'timestamp': time.time()
+        }
+
+    def move_forward(self, distance: float = 100.0):
+        """Move the camera forward by a specified distance.
+
+        Parameters
+        ----------
+        distance : float, optional
+            Distance to move in meters (default: 100.0)
+            
+        Examples
+        --------
+        >>> widget.move_forward(500)  # Move 500m forward
+        """
+        import time
+        self.camera_command = {
+            'command': 'moveForward',
+            'distance': distance,
+            'timestamp': time.time()
+        }
+
+    def move_backward(self, distance: float = 100.0):
+        """Move the camera backward by a specified distance.
 
-    def load_geojson(self, geojson):
+        Parameters
+        ----------
+        distance : float, optional
+            Distance to move in meters (default: 100.0)
+            
+        Examples
+        --------
+        >>> widget.move_backward(500)  # Move 500m backward
+        """
+        import time
+        self.camera_command = {
+            'command': 'moveBackward',
+            'distance': distance,
+            'timestamp': time.time()
+        }
+
+    def move_up(self, distance: float = 100.0):
+        """Move the camera up by a specified distance.
+
+        Parameters
+        ----------
+        distance : float, optional
+            Distance to move in meters (default: 100.0)
+            
+        Examples
+        --------
+        >>> widget.move_up(200)  # Move 200m up
+        """
+        import time
+        self.camera_command = {
+            'command': 'moveUp',
+            'distance': distance,
+            'timestamp': time.time()
+        }
+
+    def move_down(self, distance: float = 100.0):
+        """Move the camera down by a specified distance.
+
+        Parameters
+        ----------
+        distance : float, optional
+            Distance to move in meters (default: 100.0)
+            
+        Examples
+        --------
+        >>> widget.move_down(200)  # Move 200m down
+        """
+        import time
+        self.camera_command = {
+            'command': 'moveDown',
+            'distance': distance,
+            'timestamp': time.time()
+        }
+
+    def move_left(self, distance: float = 100.0):
+        """Move the camera left by a specified distance.
+
+        Parameters
+        ----------
+        distance : float, optional
+            Distance to move in meters (default: 100.0)
+            
+        Examples
+        --------
+        >>> widget.move_left(150)  # Move 150m left
+        """
+        import time
+        self.camera_command = {
+            'command': 'moveLeft',
+            'distance': distance,
+            'timestamp': time.time()
+        }
+
+    def move_right(self, distance: float = 100.0):
+        """Move the camera right by a specified distance.
+
+        Parameters
+        ----------
+        distance : float, optional
+            Distance to move in meters (default: 100.0)
+            
+        Examples
+        --------
+        >>> widget.move_right(150)  # Move 150m right
+        """
+        import time
+        self.camera_command = {
+            'command': 'moveRight',
+            'distance': distance,
+            'timestamp': time.time()
+        }
+
+    def rotate_left(self, angle: float = 15.0):
+        """Rotate the camera left (counterclockwise) by a specified angle.
+
+        Parameters
+        ----------
+        angle : float, optional
+            Rotation angle in degrees (default: 15.0)
+            
+        Examples
+        --------
+        >>> widget.rotate_left(45)  # Rotate 45° left
+        """
+        import time
+        self.camera_command = {
+            'command': 'rotateLeft',
+            'angle': angle,
+            'timestamp': time.time()
+        }
+
+    def rotate_right(self, angle: float = 15.0):
+        """Rotate the camera right (clockwise) by a specified angle.
+
+        Parameters
+        ----------
+        angle : float, optional
+            Rotation angle in degrees (default: 15.0)
+            
+        Examples
+        --------
+        >>> widget.rotate_right(45)  # Rotate 45° right
+        """
+        import time
+        self.camera_command = {
+            'command': 'rotateRight',
+            'angle': angle,
+            'timestamp': time.time()
+        }
+
+    def rotate_up(self, angle: float = 15.0):
+        """Rotate the camera up by a specified angle.
+
+        Parameters
+        ----------
+        angle : float, optional
+            Rotation angle in degrees (default: 15.0)
+            
+        Examples
+        --------
+        >>> widget.rotate_up(30)  # Look up 30°
+        """
+        import time
+        self.camera_command = {
+            'command': 'rotateUp',
+            'angle': angle,
+            'timestamp': time.time()
+        }
+
+    def rotate_down(self, angle: float = 15.0):
+        """Rotate the camera down by a specified angle.
+
+        Parameters
+        ----------
+        angle : float, optional
+            Rotation angle in degrees (default: 15.0)
+            
+        Examples
+        --------
+        >>> widget.rotate_down(30)  # Look down 30°
+        """
+        import time
+        self.camera_command = {
+            'command': 'rotateDown',
+            'angle': angle,
+            'timestamp': time.time()
+        }
+
+    def zoom_in(self, distance: float = 100.0):
+        """Zoom in (move camera closer to target).
+
+        Parameters
+        ----------
+        distance : float, optional
+            Distance to zoom in meters (default: 100.0)
+            
+        Examples
+        --------
+        >>> widget.zoom_in(500)  # Zoom in 500m
+        """
+        import time
+        self.camera_command = {
+            'command': 'zoomIn',
+            'distance': distance,
+            'timestamp': time.time()
+        }
+
+    def zoom_out(self, distance: float = 100.0):
+        """Zoom out (move camera away from target).
+
+        Parameters
+        ----------
+        distance : float, optional
+            Distance to zoom in meters (default: 100.0)
+            
+        Examples
+        --------
+        >>> widget.zoom_out(500)  # Zoom out 500m
+        """
+        import time
+        self.camera_command = {
+            'command': 'zoomOut',
+            'distance': distance,
+            'timestamp': time.time()
+        }
+
+    def set_camera(
+        self,
+        latitude=None,
+        longitude=None,
+        altitude=None,
+        heading=None,
+        pitch=None,
+        roll=None
+    ):
+        """Set individual camera parameters without full view reset.
+        
+        This allows updating only specific camera properties while keeping others unchanged.
+
+        Parameters
+        ----------
+        latitude : float, optional
+            Camera latitude in degrees
+        longitude : float, optional
+            Camera longitude in degrees
+        altitude : float, optional
+            Camera altitude in meters
+        heading : float, optional
+            Camera heading in degrees
+        pitch : float, optional
+            Camera pitch in degrees
+        roll : float, optional
+            Camera roll in degrees
+            
+        Examples
+        --------
+        >>> widget.set_camera(pitch=-45)  # Only change pitch
+        >>> widget.set_camera(heading=90, altitude=5000)  # Change heading and altitude
+        """
+        if latitude is not None:
+            self.latitude = latitude
+        if longitude is not None:
+            self.longitude = longitude
+        if altitude is not None:
+            self.altitude = altitude
+        if heading is not None:
+            self.heading = heading
+        if pitch is not None:
+            self.pitch = pitch
+        if roll is not None:
+            self.roll = roll
+
+    def load_geojson(self, geojson, append=False):
         """Load GeoJSON data for visualization.
 
         Parameters
         ----------
-        geojson : dict
-            GeoJSON dictionary or GeoJSON object
+        geojson : dict or str
+            GeoJSON dictionary or GeoJSON string
+        append : bool, optional
+            If True, append to existing GeoJSON data. If False (default), replace existing data.
+            
+        Examples
+        --------
+        Load a single GeoJSON (replaces existing):
+        >>> widget.load_geojson({"type": "FeatureCollection", "features": [...]})
+        
+        Load multiple GeoJSON datasets:
+        >>> widget.load_geojson(geojson1)
+        >>> widget.load_geojson(geojson2, append=True)  # Adds to existing data
         """
         if isinstance(geojson, str):
             import json
-
             geojson = json.loads(geojson)
-        self.geojson_data = geojson
+        
+        if append:
+            # Append to existing list
+            current_data = list(self.geojson_data)
+            current_data.append(geojson)
+            self.geojson_data = current_data
+        else:
+            # Replace existing data
+            self.geojson_data = [geojson]
+    
+    def clear_geojson(self):
+        """Clear all GeoJSON data from the viewer.
+        
+        Examples
+        --------
+        >>> widget.clear_geojson()
+        """
+        self.geojson_data = []
 
-    def load_czml(self, czml: str | list):
+    def load_czml(self, czml: str | list, append=False):
         """Load CZML data for visualization.
 
         CZML (Cesium Language) is a JSON format for describing time-dynamic
@@ -192,6 +614,8 @@ class CesiumWidget(anywidget.AnyWidget):
         ----------
         czml : str or list
             CZML document as a JSON string or list of packet dictionaries.
+        append : bool, optional
+            If True, append to existing CZML data. If False (default), replace existing data.
 
         Examples
         --------
@@ -208,6 +632,11 @@ class CesiumWidget(anywidget.AnyWidget):
         ...     {"id": "point", "position": {"cartographicDegrees": [-74, 40, 0]}}
         ... ]
         >>> widget.load_czml(czml)
+        
+        Append multiple CZML documents:
+        >>> widget.load_czml(czml_doc1)
+        >>> widget.load_czml(czml_doc2, append=True)  # Adds to existing data
+        >>> widget.load_czml(new_czml, clear_existing=True)
         """
         import json
 
@@ -223,7 +652,23 @@ class CesiumWidget(anywidget.AnyWidget):
         if len(czml) == 0:
             raise ValueError("CZML document must contain at least one packet")
 
-        self.czml_data = czml
+        if append:
+            # Append to existing list
+            current_data = list(self.czml_data)
+            current_data.append(czml)
+            self.czml_data = current_data
+        else:
+            # Replace existing data
+            self.czml_data = [czml]
+    
+    def clear_czml(self):
+        """Clear all CZML data from the viewer.
+        
+        Examples
+        --------
+        >>> widget.clear_czml()
+        """
+        self.czml_data = []
 
     def enable_measurement(self, mode: str = "distance"):
         """Enable a measurement tool.
@@ -329,6 +774,272 @@ class CesiumWidget(anywidget.AnyWidget):
         """Hide the measurements list panel."""
         self.show_measurements_list = False
 
+    def set_atmosphere(self, 
+                      brightness_shift=None, 
+                      hue_shift=None, 
+                      saturation_shift=None,
+                      light_intensity=None,
+                      rayleigh_coefficient=None,
+                      rayleigh_scale_height=None,
+                      mie_coefficient=None,
+                      mie_scale_height=None,
+                      mie_anisotropy=None):
+        """Configure atmosphere rendering settings.
+        
+        Parameters
+        ----------
+        brightness_shift : float, optional
+            Brightness shift to apply (-1.0 to 1.0). Default 0.0 (no shift).
+            -1.0 is complete darkness, letting space show through.
+        hue_shift : float, optional
+            Hue shift to apply (0.0 to 1.0). Default 0.0 (no shift).
+            1.0 indicates a complete rotation of hues.
+        saturation_shift : float, optional
+            Saturation shift to apply (-1.0 to 1.0). Default 0.0 (no shift).
+            -1.0 is monochrome.
+        light_intensity : float, optional
+            Intensity of light for ground atmosphere color computation.
+        rayleigh_coefficient : tuple of 3 floats, optional
+            Rayleigh scattering coefficient (x, y, z components).
+        rayleigh_scale_height : float, optional
+            Rayleigh scale height in meters.
+        mie_coefficient : tuple of 3 floats, optional
+            Mie scattering coefficient (x, y, z components).
+        mie_scale_height : float, optional
+            Mie scale height in meters.
+        mie_anisotropy : float, optional
+            Anisotropy of medium for Mie scattering (-1.0 to 1.0).
+            
+        Examples
+        --------
+        Make atmosphere darker:
+        >>> widget.set_atmosphere(brightness_shift=-0.3)
+        
+        Change hue (e.g., for alien planet effect):
+        >>> widget.set_atmosphere(hue_shift=0.3, saturation_shift=0.2)
+        
+        Desaturate atmosphere:
+        >>> widget.set_atmosphere(saturation_shift=-0.5)
+        
+        Reset to defaults:
+        >>> widget.set_atmosphere(brightness_shift=0, hue_shift=0, saturation_shift=0)
+        """
+        settings = {}
+        
+        if brightness_shift is not None:
+            settings['brightnessShift'] = brightness_shift
+        if hue_shift is not None:
+            settings['hueShift'] = hue_shift
+        if saturation_shift is not None:
+            settings['saturationShift'] = saturation_shift
+        if light_intensity is not None:
+            settings['lightIntensity'] = light_intensity
+        if rayleigh_coefficient is not None:
+            if len(rayleigh_coefficient) != 3:
+                raise ValueError("rayleigh_coefficient must be a tuple of 3 floats")
+            settings['rayleighCoefficient'] = list(rayleigh_coefficient)
+        if rayleigh_scale_height is not None:
+            settings['rayleighScaleHeight'] = rayleigh_scale_height
+        if mie_coefficient is not None:
+            if len(mie_coefficient) != 3:
+                raise ValueError("mie_coefficient must be a tuple of 3 floats")
+            settings['mieCoefficient'] = list(mie_coefficient)
+        if mie_scale_height is not None:
+            settings['mieScaleHeight'] = mie_scale_height
+        if mie_anisotropy is not None:
+            settings['mieAnisotropy'] = mie_anisotropy
+            
+        self.atmosphere_settings = settings
+
+    def set_sky_atmosphere(self,
+                          show=None,
+                          brightness_shift=None,
+                          hue_shift=None,
+                          saturation_shift=None,
+                          light_intensity=None,
+                          rayleigh_coefficient=None,
+                          rayleigh_scale_height=None,
+                          mie_coefficient=None,
+                          mie_scale_height=None,
+                          mie_anisotropy=None,
+                          per_fragment_atmosphere=None):
+        """Configure sky atmosphere rendering settings.
+        
+        The sky atmosphere is drawn around the limb of the ellipsoid and is only
+        visible in 3D mode (fades out in 2D/Columbus view).
+        
+        Parameters
+        ----------
+        show : bool, optional
+            Whether to show the sky atmosphere.
+        brightness_shift : float, optional
+            Brightness shift to apply (-1.0 to 1.0). Default 0.0 (no shift).
+            -1.0 is complete darkness, letting space show through.
+        hue_shift : float, optional
+            Hue shift to apply (0.0 to 1.0). Default 0.0 (no shift).
+            1.0 indicates a complete rotation of hues.
+        saturation_shift : float, optional
+            Saturation shift to apply (-1.0 to 1.0). Default 0.0 (no shift).
+            -1.0 is monochrome.
+        light_intensity : float, optional
+            Intensity of light for sky atmosphere color computation.
+        rayleigh_coefficient : tuple of 3 floats, optional
+            Rayleigh scattering coefficient (x, y, z components).
+        rayleigh_scale_height : float, optional
+            Rayleigh scale height in meters.
+        mie_coefficient : tuple of 3 floats, optional
+            Mie scattering coefficient (x, y, z components).
+        mie_scale_height : float, optional
+            Mie scale height in meters.
+        mie_anisotropy : float, optional
+            Anisotropy of medium for Mie scattering (-1.0 to 1.0).
+        per_fragment_atmosphere : bool, optional
+            Compute atmosphere per-fragment (better quality, slight performance cost).
+            
+        Examples
+        --------
+        Hide sky atmosphere:
+        >>> widget.set_sky_atmosphere(show=False)
+        
+        Make sky darker:
+        >>> widget.set_sky_atmosphere(brightness_shift=-0.3)
+        
+        Change sky color:
+        >>> widget.set_sky_atmosphere(hue_shift=0.2, saturation_shift=0.1)
+        
+        Enable per-fragment rendering:
+        >>> widget.set_sky_atmosphere(per_fragment_atmosphere=True)
+        
+        Reset:
+        >>> widget.sky_atmosphere_settings = {}
+        """
+        settings = {}
+        
+        if show is not None:
+            settings['show'] = show
+        if brightness_shift is not None:
+            settings['brightnessShift'] = brightness_shift
+        if hue_shift is not None:
+            settings['hueShift'] = hue_shift
+        if saturation_shift is not None:
+            settings['saturationShift'] = saturation_shift
+        if light_intensity is not None:
+            settings['atmosphereLightIntensity'] = light_intensity
+        if rayleigh_coefficient is not None:
+            if len(rayleigh_coefficient) != 3:
+                raise ValueError("rayleigh_coefficient must be a tuple of 3 floats")
+            settings['atmosphereRayleighCoefficient'] = list(rayleigh_coefficient)
+        if rayleigh_scale_height is not None:
+            settings['atmosphereRayleighScaleHeight'] = rayleigh_scale_height
+        if mie_coefficient is not None:
+            if len(mie_coefficient) != 3:
+                raise ValueError("mie_coefficient must be a tuple of 3 floats")
+            settings['atmosphereMieCoefficient'] = list(mie_coefficient)
+        if mie_scale_height is not None:
+            settings['atmosphereMieScaleHeight'] = mie_scale_height
+        if mie_anisotropy is not None:
+            settings['atmosphereMieAnisotropy'] = mie_anisotropy
+        if per_fragment_atmosphere is not None:
+            settings['perFragmentAtmosphere'] = per_fragment_atmosphere
+            
+        self.sky_atmosphere_settings = settings
+
+    def set_skybox(self,
+                  show=None,
+                  sources=None):
+        """Configure skybox rendering settings.
+        
+        The skybox is the cube map displayed around the scene. You can show/hide it
+        or provide custom cube map sources.
+        
+        Parameters
+        ----------
+        show : bool, optional
+            Whether to show the skybox.
+        sources : dict, optional
+            Custom cube map sources with keys:
+            - 'positiveX': URL for +X face (right)
+            - 'negativeX': URL for -X face (left)
+            - 'positiveY': URL for +Y face (top)
+            - 'negativeY': URL for -Y face (bottom)
+            - 'positiveZ': URL for +Z face (front)
+            - 'negativeZ': URL for -Z face (back)
+            
+        Examples
+        --------
+        Hide skybox:
+        >>> widget.set_skybox(show=False)
+        
+        Show skybox:
+        >>> widget.set_skybox(show=True)
+        
+        Custom skybox:
+        >>> widget.set_skybox(sources={
+        ...     'positiveX': 'path/to/right.jpg',
+        ...     'negativeX': 'path/to/left.jpg',
+        ...     'positiveY': 'path/to/top.jpg',
+        ...     'negativeY': 'path/to/bottom.jpg',
+        ...     'positiveZ': 'path/to/front.jpg',
+        ...     'negativeZ': 'path/to/back.jpg'
+        ... })
+        """
+        settings = {}
+        
+        if show is not None:
+            settings['show'] = show
+            
+        if sources is not None:
+            if not isinstance(sources, dict):
+                raise ValueError("sources must be a dictionary with cube map face URLs")
+            
+            # Validate that all required faces are provided if sources is given
+            required_faces = {'positiveX', 'negativeX', 'positiveY', 'negativeY', 'positiveZ', 'negativeZ'}
+            provided_faces = set(sources.keys())
+            
+            if provided_faces and not required_faces.issubset(provided_faces):
+                missing = required_faces - provided_faces
+                raise ValueError(f"sources must include all cube map faces. Missing: {missing}")
+            
+            settings['sources'] = sources
+            
+        self.skybox_settings = settings
+
+    def on_interaction(self, callback):
+        """Register a callback for user interaction events.
+        
+        The callback will be called when any user interaction ends (camera movement,
+        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
+        - camera: Camera state (latitude, longitude, altitude, heading, pitch, roll)
+        - clock: Clock state (current_time, multiplier, is_animating) if timeline enabled
+        - picked_position: Coordinates of clicked location (if applicable)
+        - picked_entity: Information about clicked entity (if applicable)
+        
+        Parameters
+        ----------
+        callback : callable
+            Function to call with interaction event data: callback(event_data)
+            
+        Examples
+        --------
+        >>> def handle_interaction(event):
+        ...     print(f"Interaction: {event['type']}")
+        ...     print(f"Camera at: {event['camera']['latitude']}, {event['camera']['longitude']}")
+        ...     if 'picked_position' in event:
+        ...         print(f"Clicked: {event['picked_position']}")
+        >>> 
+        >>> widget.on_interaction(handle_interaction)
+        """
+        def wrapper(change):
+            event_data = change['new']
+            if event_data and event_data.get('timestamp'):  # Only call if valid event
+                callback(event_data)
+        
+        self.observe(wrapper, names='interaction_event')
+        return wrapper  # Return so user can unobserve if needed
+
     def debug_info(self):
         """Print debug information about the widget.
 

{cesiumjs_anywidget-0.2.4.dist-info → cesiumjs_anywidget-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cesiumjs-anywidget
-Version: 0.2.4
+Version: 0.3.0
 Summary: A Jupyter widget for CesiumJS 3D globe visualization using anywidget
 Project-URL: Homepage, https://github.com/Alex-PLACET/cesiumjs_anywidget
 Project-URL: Repository, https://github.com/Alex-PLACET/cesiumjs_anywidget

cesiumjs_anywidget-0.3.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+cesiumjs_anywidget/__init__.py,sha256=9WVcAtreHgk6C5clPG6sZy4m7s5AIbGU1DJ4oDpx3Is,165
+cesiumjs_anywidget/styles.css,sha256=kt2i9fJuM6gaR7WkoQ2VGGoHzhqy6RpJVK2xwMKPV70,689
+cesiumjs_anywidget/widget.py,sha256=_7uXX7B3KsOg_3QrMDfV0pZ8BGA-6coFnZ7_gTI3nck,39104
+cesiumjs_anywidget/index.js,sha256=eSZZJhS2-3UDipN3KkXpxUMTgx4Jzs8sSHAWSjhUnHU,67449
+cesiumjs_anywidget-0.3.0.dist-info/METADATA,sha256=eTd0CCg94JXQ5ezxPvZGyyvJG_ZSCIu41jkYCUav5cs,24778
+cesiumjs_anywidget-0.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+cesiumjs_anywidget-0.3.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+cesiumjs_anywidget-0.3.0.dist-info/RECORD,,

cesiumjs_anywidget-0.2.4.dist-info/RECORD

@@ -1,8 +0,0 @@
-cesiumjs_anywidget/__init__.py,sha256=9WVcAtreHgk6C5clPG6sZy4m7s5AIbGU1DJ4oDpx3Is,165
-cesiumjs_anywidget/styles.css,sha256=kt2i9fJuM6gaR7WkoQ2VGGoHzhqy6RpJVK2xwMKPV70,689
-cesiumjs_anywidget/widget.py,sha256=7RnZgQxkiKso6CjH4ciZi4JjJwBOI-cxuXRd2Ap7WGM,13646
-cesiumjs_anywidget/index.js,sha256=6vqb7UM8cxeJyuyDIw2IJcsaPXRjKsSRCXbWEJNTmZk,54315
-cesiumjs_anywidget-0.2.4.dist-info/METADATA,sha256=ToDMpPDZ9wUGJPLGjOML5ElawxeYUTtz3WTWqOBi9r8,24778
-cesiumjs_anywidget-0.2.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-cesiumjs_anywidget-0.2.4.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-cesiumjs_anywidget-0.2.4.dist-info/RECORD,,