cesiumjs-anywidget 0.2.4__py3-none-any.whl

cesiumjs_anywidget-0.2.4.dist-info/METADATA

@@ -0,0 +1,624 @@
+Metadata-Version: 2.4
+Name: cesiumjs-anywidget
+Version: 0.2.4
+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
+Author: Alex PLACET
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "[]"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright [yyyy] [name of copyright owner]
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Requires-Dist: anywidget>=0.9.0
+Requires-Dist: traitlets>=5.0.0
+Provides-Extra: dev
+Requires-Dist: jupyterlab>=4.0.0; extra == 'dev'
+Requires-Dist: notebook>=7.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CesiumJS Anywidget
+
+A Jupyter widget for interactive 3D globe visualization using [CesiumJS](https://cesium.com/cesiumjs/) and [anywidget](https://anywidget.dev/).
+
+## Features
+
+- 🌍 **Interactive 3D Globe**: Full CesiumJS viewer integration
+- 🎯 **Camera Control**: Fly to locations with smooth animations
+- 🔄 **Bidirectional Sync**: Camera state syncs between Python and JavaScript
+- 🗺️ **GeoJSON Support**: Load and visualize GeoJSON data
+- 🏔️ **Terrain & Imagery**: World terrain and satellite imagery
+- 📏 **Measurement Tools**: Built-in distance, multi-point, and height measurement tools
+- ⚙️ **Highly Configurable**: Customize viewer options and UI elements
+
+## Installation
+
+Using uv (recommended):
+
+```bash
+uv pip install cesiumjs-anywidget
+```
+
+Or for development:
+
+```bash
+git clone https://github.com/Alex-PLACET/cesiumjs_anywidget.git
+cd cesiumjs_anywidget
+uv pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from cesiumjs_anywidget import CesiumWidget
+
+# Create and display the widget
+widget = CesiumWidget(height="700px")
+widget
+```
+
+## Usage Examples
+
+### Fly to a Location
+
+```python
+# Fly to New York City
+widget.fly_to(latitude=40.7128, longitude=-74.0060, altitude=50000)
+
+# Fly to Mount Everest
+widget.fly_to(latitude=27.9881, longitude=86.9250, altitude=20000)
+```
+
+### Advanced Camera Control
+
+```python
+# Set camera with custom orientation
+widget.set_view(
+    latitude=40.7128, 
+    longitude=-74.0060, 
+    altitude=5000,
+    heading=45.0,    # Rotate view 45 degrees
+    pitch=-45.0,     # Look at angle instead of straight down
+    roll=0.0
+)
+```
+
+### Read Camera State
+
+```python
+# Camera position is synchronized bidirectionally
+print(f"Latitude: {widget.latitude:.4f}°")
+print(f"Longitude: {widget.longitude:.4f}°")
+print(f"Altitude: {widget.altitude:.2f} meters")
+```
+
+### Visualize GeoJSON Data
+
+```python
+geojson_data = {
+    "type": "FeatureCollection",
+    "features": [
+        {
+            "type": "Feature",
+            "geometry": {
+                "type": "Point",
+                "coordinates": [-74.0060, 40.7128]
+            },
+            "properties": {
+                "name": "New York City"
+            }
+        }
+    ]
+}
+
+widget.load_geojson(geojson_data)
+```
+
+### Visualize CZML Data
+
+CZML (Cesium Language) is a JSON format for describing time-dynamic graphical scenes. It's particularly useful for animations and complex visualizations.
+
+```python
+# Simple CZML example - as Python list
+czml_data = [
+    {
+        "id": "document",
+        "name": "Simple CZML",
+        "version": "1.0"
+    },
+    {
+        "id": "point",
+        "name": "Location",
+        "position": {
+            "cartographicDegrees": [-74.0060, 40.7128, 0]
+        },
+        "point": {
+            "pixelSize": 10,
+            "color": {
+                "rgba": [255, 0, 0, 255]
+            }
+        }
+    }
+]
+
+widget.load_czml(czml_data)
+```
+
+Or from a JSON string:
+
+```python
+import json
+
+# CZML as JSON string
+czml_json = json.dumps([
+    {"id": "document", "version": "1.0"},
+    {
+        "id": "satellite",
+        "position": {
+            "cartographicDegrees": [-75, 40, 500000]
+        },
+        "point": {"pixelSize": 8, "color": {"rgba": [0, 255, 0, 255]}}
+    }
+])
+
+widget.load_czml(czml_json)
+```
+
+You can use the [czml3](https://github.com/Stoops-ML/czml3) library to generate CZML more easily, then pass the output as a string or list.
+
+### Configure Viewer Options
+
+```python
+# Create widget with custom configuration
+widget = CesiumWidget(
+    height="700px",
+    enable_terrain=True,
+    enable_lighting=True,
+    show_timeline=True,
+    show_animation=True,
+    latitude=27.9881,
+    longitude=86.9250,
+    altitude=30000
+)
+```
+
+## Development
+
+Enable hot module replacement for live updates during development:
+
+```bash
+export ANYWIDGET_HMR=1
+jupyter lab
+```
+
+### Running Tests
+
+```bash
+# Install with dev dependencies
+uv pip install -e ".[dev]"
+
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=cesiumjs_anywidget --cov-report=html
+
+# Or use make
+make test
+make test-cov
+```
+
+See [tests/README.md](tests/README.md) for detailed testing documentation.
+
+## Measurement Tools
+
+The widget includes built-in measurement tools for spatial analysis:
+
+### Distance Measurement
+
+Measure the distance between two points:
+
+```python
+# Enable distance measurement mode
+widget.enable_measurement(mode="distance")
+
+# Click two points in the viewer to measure distance
+# Results are automatically synced to Python
+measurements = widget.get_measurements()
+print(f"Distance: {measurements[0]['value']:.2f} meters")
+```
+
+### Multi-Point Distance Measurement
+
+Measure distances along a polyline with multiple points:
+
+```python
+# Enable multi-point distance measurement
+widget.enable_measurement(mode="multi-distance")
+
+# Click multiple points to create a polyline
+# Right-click to finish the measurement
+# Total distance is calculated automatically
+```
+
+### Height Measurement
+
+Measure vertical height from ground to a point (useful for buildings):
+
+```python
+# Enable height measurement
+widget.enable_measurement(mode="height")
+
+# Click on a point to measure its height above ground
+measurements = widget.get_measurements()
+print(f"Height: {measurements[0]['value']:.2f} meters")
+```
+
+### Managing Measurements
+
+```python
+# Get all measurement results
+measurements = widget.get_measurements()
+for m in measurements:
+    print(f"Type: {m['type']}, Value: {m['value']:.2f}m")
+
+# Clear all measurements
+widget.clear_measurements()
+
+# Disable measurement mode
+widget.disable_measurement()
+```
+
+### Loading Measurements from Python
+
+You can programmatically add measurements with specific coordinates:
+
+```python
+# Load a distance measurement between two points
+measurements_data = [
+    {
+        "type": "distance",
+        "name": "Bridge Length",
+        "points": [
+            {"coordinates": [-74.0445, 40.6892, 10]},  # [lon, lat, alt]
+            {"coordinates": [-73.9626, 40.8075, 10]}
+        ]
+    }
+]
+widget.load_measurements(measurements_data)
+
+# Load an area measurement (polygon)
+area_data = [
+    {
+        "type": "area",
+        "name": "Central Park",
+        "points": [
+            {"coordinates": [-73.9812, 40.7681, 0]},
+            {"coordinates": [-73.9581, 40.7681, 0]},
+            {"coordinates": [-73.9581, 40.8005, 0]},
+            {"coordinates": [-73.9812, 40.8005, 0]}
+        ]
+    }
+]
+widget.load_measurements(area_data)
+
+# Focus camera on a specific measurement
+widget.focus_on_measurement(0)  # Focus on first measurement
+```
+
+### Controlling Measurement UI Visibility
+
+You can show/hide the measurement tools and list panel:
+
+```python
+# Hide measurement tools (toolbar)
+widget.hide_tools()
+# Or: widget.show_measurement_tools = False
+
+# Show tools again
+widget.show_tools()
+# Or: widget.show_measurement_tools = True
+
+# Hide the measurements list panel
+widget.hide_list()
+# Or: widget.show_measurements_list = False
+
+# Show list again
+widget.show_list()
+# Or: widget.show_measurements_list = True
+
+# Create a clean viewer without measurement tools
+widget = CesiumWidget(
+    show_measurement_tools=False,
+    show_measurements_list=False
+)
+```
+
+Each measurement includes:
+- `type`: Measurement type (`'distance'`, `'multi-distance'`, `'height'`, or `'area'`)
+- `value`: Measured value in meters (distance) or square meters (area)
+- `points`: List of coordinates with `lat`, `lon`, `alt` properties
+- `name`: Optional name for the measurement (auto-generated if not provided)
+
+## API Reference
+
+### CesiumWidget
+
+**Parameters:**
+- `latitude` (float): Camera latitude in degrees (default: 0.0)
+- `longitude` (float): Camera longitude in degrees (default: 0.0)
+- `altitude` (float): Camera altitude in meters (default: 20000000.0)
+- `heading` (float): Camera heading in degrees (default: 0.0)
+- `pitch` (float): Camera pitch in degrees (default: -90.0)
+- `roll` (float): Camera roll in degrees (default: 0.0)
+- `height` (str): Widget height CSS value (default: "600px")
+- `enable_terrain` (bool): Enable terrain visualization (default: True)
+- `enable_lighting` (bool): Enable scene lighting (default: False)
+- `show_timeline` (bool): Show timeline widget (default: False)
+- `show_animation` (bool): Show animation widget (default: False)
+- `ion_access_token` (str): Cesium Ion access token (optional)
+- `geojson_data` (dict): GeoJSON data to display (optional)
+- `czml_data` (list): CZML data to display (optional)
+- `measurement_mode` (str): Active measurement mode (default: "")
+- `measurement_results` (list): List of measurement results (default: [])
+- `show_measurement_tools` (bool): Show measurement toolbar (default: True)
+- `show_measurements_list` (bool): Show measurements list panel (default: True)
+
+**Methods:**
+- `fly_to(latitude, longitude, altitude=10000, duration=3.0)`: Fly camera to location
+- `set_view(latitude, longitude, altitude=10000, heading=0.0, pitch=-90.0, roll=0.0)`: Set camera view instantly
+- `load_geojson(geojson)`: Load GeoJSON data for visualization
+- `load_czml(czml)`: Load CZML data for time-dynamic visualization
+- `enable_measurement(mode="distance")`: Enable measurement tool (modes: 'distance', 'multi-distance', 'height', 'area')
+- `disable_measurement()`: Disable measurement tool
+- `get_measurements()`: Get all measurement results
+- `clear_measurements()`: Clear all measurements from viewer
+- `load_measurements(measurements)`: Load measurements from Python data
+- `focus_on_measurement(index)`: Fly camera to specific measurement
+- `show_tools()`: Show the measurement tools toolbar
+- `hide_tools()`: Hide the measurement tools toolbar
+- `show_list()`: Show the measurements list panel
+- `hide_list()`: Hide the measurements list panel
+
+## Examples
+
+See the [examples](examples/) directory for Jupyter notebook demonstrations.
+
+## Troubleshooting
+
+If you encounter issues with widget initialization:
+
+```python
+from cesiumjs_anywidget import CesiumWidget
+widget = CesiumWidget()
+widget.debug_info()  # Show debug information
+```
+
+Common fixes:
+- **Open browser DevTools (F12)** and check the Console tab for errors
+- Try without terrain: `widget = CesiumWidget(enable_terrain=False)`
+- Ensure you're using JupyterLab 4.0+ or Jupyter Notebook 7.0+
+- Check internet connection (CesiumJS loads from CDN)
+
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed debugging guide.
+
+## License
+
+Apache License 2.0 - see [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built with [anywidget](https://anywidget.dev/)
+- Powered by [CesiumJS](https://cesium.com/cesiumjs/)
+- Uses [Cesium Ion](https://cesium.com/ion/) for terrain and imagery

cesiumjs_anywidget-0.2.4.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=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,,

cesiumjs_anywidget-0.2.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any