czml3

https://github.com/stoops-ml/czml3
Admin
czml3 is a Python library that simplifies writing CZML files for Cesium with type checking, data...
Tokens:10,309
Snippets:63
Trust Score:7.2
License:BSD-3-Clause
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install czml3 via package managers

Source: https://github.com/stoops-ml/czml3/blob/main/docs/user/installation.md

Use these commands to install the library in your local environment.

```default
pip install czml3
```

```default
conda install czml3 --channel conda-forge
```

--------------------------------

### Install czml3 using pip

Source: https://github.com/stoops-ml/czml3/blob/main/README.md

Use this command to install the czml3 library via pip.

```bash
pip install czml3
```

--------------------------------

### Install czml3 using conda

Source: https://github.com/stoops-ml/czml3/blob/main/README.md

Use this command to install the czml3 library via conda.

```bash
conda install czml3 --channel conda-forge
```

--------------------------------

### Import 3D Models in CZML

Source: https://context7.com/stoops-ml/czml3/llms.txt

Setup for loading glTF 3D models into a CZML document.

```python
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import Color, Model, Orientation, Position
from czml3.types import UnitQuaternionValue
```

--------------------------------

### Create a CZML Document with a Box Packet

Source: https://github.com/stoops-ml/czml3/blob/main/README.md

This example demonstrates creating a CZML document containing a packet for a blue box with specified dimensions and position. It utilizes various properties from the czml3 library, including Position, Box, BoxDimensions, Material, SolidColorMaterial, and Color.

```python
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import (
    Box,
    BoxDimensions,
    Color,
    Material,
    Position,
    SolidColorMaterial,
)
from czml3.types import Cartesian3Value
packet_box = Packet(
    id="my_id",
    position=Position(cartographicDegrees=[-114.0, 40.0, 300000.0]),
    box=Box(
        dimensions=BoxDimensions(
            cartesian=Cartesian3Value(values=[400000.0, 300000.0, 500000.0])
        ),
        material=Material(
            solidColor=SolidColorMaterial(color=Color(rgba=[0, 0, 255, 255]))
        ),
    ),
)
doc = Document(
    packets=[Packet(id="document", name="box", version=CZML_VERSION), packet_box]
)
print(doc)
```

```json
[
    {
        "id": "document",
        "name": "box",
        "version": "1.0"
    },
    {
        "id": "my_id",
        "position": {
            "cartographicDegrees": [
                -114.0,
                40.0,
                300000.0
            ]
        },
        "box": {
            "dimensions": {
                "cartesian": [
                    400000.0,
                    300000.0,
                    500000.0
                ]
            },
            "material": {
                "solidColor": {
                    "color": {
                        "rgba": [
                            0.0,
                            0.0,
                            255.0,
                            255.0
                        ]
                    }
                }
            }
        }
    }
]
```

--------------------------------

### Create a Styled Text Label

Source: https://context7.com/stoops-ml/czml3/llms.txt

Defines a text label with custom font, fill and outline colors, and background. Ensure 'czml3' is installed for this functionality.

```python
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import Color, Label, Position
from czml3.enums import HorizontalOrigins, LabelStyles, VerticalOrigins

# Create a styled label
packet_label = Packet(
    id="label1",
    name="Pennsylvania",
    position=Position(cartesian=[1152255.80, -4694317.95, 4147335.90]),
    label=Label(
        text="Pennsylvania",
        font="14pt Helvetica",
        style=LabelStyles.FILL_AND_OUTLINE,
        fillColor=Color(rgba=[255, 255, 0, 255]),
        outlineColor=Color(rgba=[0, 0, 0, 255]),
        outlineWidth=2.0,
        horizontalOrigin=HorizontalOrigins.LEFT,
        verticalOrigin=VerticalOrigins.CENTER,
        showBackground=True,
        backgroundColor=Color(rgba=[0, 0, 128, 200]),
        show=True
    )
)

doc = Document(packets=[
    Packet(id="document", name="labels", version=CZML_VERSION),
    packet_label
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Create a Red Point with White Outline

Source: https://context7.com/stoops-ml/czml3/llms.txt

Defines a point marker with specific pixel size, red fill color, and a white outline. Ensure the 'czml3' library is installed.

```python
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import Color, Point, Position

packet_point = Packet(
    id="point1",
    name="Point Marker",
    position=Position(cartographicDegrees=[-75.0, 40.0, 0.0]),
    point=Point(
        pixelSize=20.0,
        color=Color(rgba=[255, 0, 0, 255]),
        outlineColor=Color(rgba=[255, 255, 255, 255]),
        outlineWidth=2.0,
        show=True
    )
)

doc = Document(packets=[
    Packet(id="document", name="points", version=CZML_VERSION),
    packet_point
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Define Point Primitive

Source: https://context7.com/stoops-ml/czml3/llms.txt

Example of creating a Packet for a Point primitive, which is a viewport-aligned circle. It uses the packet's position property for location and can be styled with color and outline.

```python
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import Color, Point, Position
```

--------------------------------

### Coerce Data Types for Position Property

Source: https://github.com/stoops-ml/czml3/blob/main/docs/user/examples.md

Demonstrates how czml3, using pydantic, can coerce data types. This example shows a numpy array of integers being converted to doubles for the cartographicDegrees property of a Position object.

```python
import numpy as np
from czml3.properties import Position
print(Position(cartographicDegrees=np.array([-114, 40, 300000], dtype=int)))
```

--------------------------------

### Create a CZML Document with Preamble and Object

Source: https://context7.com/stoops-ml/czml3/llms.txt

Demonstrates the core CZML structure: a Document packet with preamble and subsequent packets for objects. Ensure the first packet has 'id="document"'.

```python
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import Position

# Create a CZML document with a preamble and one object packet
doc = Document(
    packets=[
        Packet(id="document", name="MyDocument", version=CZML_VERSION),
        Packet(
            id="my_point",
            name="My Point",
            position=Position(cartographicDegrees=[-75.0, 40.0, 0.0])
        )
    ]
)

# Output as JSON string
print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Create Various Material Types

Source: https://context7.com/stoops-ml/czml3/llms.txt

Supports solid colors, images, grids, stripes, and checkerboard patterns for styling surfaces. Ensure correct Color and Uri objects are used.

```python
from czml3.properties import (
    CheckerboardMaterial, Color, GridMaterial, ImageMaterial,
    Material, StripeMaterial, SolidColorMaterial, Uri
)
from czml3.enums import StripeOrientations

# Solid color material
solid = Material(
    solidColor=SolidColorMaterial(color=Color(rgba=[255, 0, 0, 255]))
)

# Grid material
grid = Material(
    grid=GridMaterial(
        color=Color(rgba=[0, 255, 255, 128]),
        cellAlpha=0.2,
        lineCount=[8, 8],
        lineThickness=[2.0, 2.0]
    )
)

# Stripe material
stripe = Material(
    stripe=StripeMaterial(
        orientation=StripeOrientations.HORIZONTAL,
        evenColor=Color(rgba=[255, 255, 255, 255]),
        oddColor=Color(rgba=[0, 0, 255, 255]),
        repeat=5.0
    )
)

# Image material
image = Material(
    image=ImageMaterial(
        image=Uri(uri="https://example.com/texture.png"),
        repeat=[4, 4]
    )
)

# Checkerboard material
checker = Material(
    checkerboard=CheckerboardMaterial(
        evenColor=Color(rgba=[0, 0, 0, 255]),
        oddColor=Color(rgba=[255, 255, 255, 255]),
        repeat=[10, 10]
    )
)

print(grid.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Define Time-Dynamic Positions with Interpolation

Source: https://context7.com/stoops-ml/czml3/llms.txt

Shows how to define time-dynamic positions using interpolation algorithms like LAGRANGE for smooth animation. Requires epoch and time-tagged sample data.

```python
from czml3.properties import Position
from czml3.types import Cartesian3Value
from czml3.enums import InterpolationAlgorithms, ReferenceFrames
import datetime as dt

# Time-dynamic position with interpolation for satellite tracking
start = dt.datetime(2024, 1, 1, tzinfo=dt.timezone.utc)
animated_pos = Position(
    interpolationAlgorithm=InterpolationAlgorithms.LAGRANGE,
    interpolationDegree=5,
    referenceFrame=ReferenceFrames.INERTIAL,
    epoch=start,
    cartesian=[
        0, 4650397.56, -3390535.52, -4087729.48,      # t=0 seconds
        300, 3169722.12, -2787480.80, -5661647.74,    # t=300 seconds
        600, 1369743.14, -1903662.23, -6663952.07,    # t=600 seconds
    ]
)
```

--------------------------------

### Visualize motion trails

Source: https://context7.com/stoops-ml/czml3/llms.txt

Configures a satellite trajectory using interpolation algorithms and path visualization settings.

```python
import datetime as dt
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import (
    Color, Path, PolylineMaterial, Position, SolidColorMaterial
)
from czml3.types import IntervalValue, TimeIntervalCollection
from czml3.enums import InterpolationAlgorithms, ReferenceFrames

start = dt.datetime(2024, 1, 1, tzinfo=dt.timezone.utc)
end = dt.datetime(2024, 1, 2, tzinfo=dt.timezone.utc)

# Satellite with orbital path visualization
satellite = Packet(
    id="satellite1",
    name="ISS",
    position=Position(
        interpolationAlgorithm=InterpolationAlgorithms.LAGRANGE,
        interpolationDegree=5,
        referenceFrame=ReferenceFrames.INERTIAL,
        epoch=start,
        cartesian=[
            0, 4650397.56, -3390535.52, -4087729.48,
            3600, -6000251.41, 3168038.65, -1983402.41,
            7200, 6028480.33, -3610312.82, -617627.59,
        ]
    ),
    path=Path(
        show=TimeIntervalCollection(
            values=[IntervalValue(start=start, end=end, value=True)]
        ),
        width=2.0,
        leadTime=3600.0,
        trailTime=3600.0,
        resolution=60.0,
        material=PolylineMaterial(
            solidColor=SolidColorMaterial(color=Color(rgba=[0, 255, 0, 255]))
        )
    )
)

doc = Document(packets=[
    Packet(id="document", name="satellite_track", version=CZML_VERSION),
    satellite
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Configure animation clock

Source: https://context7.com/stoops-ml/czml3/llms.txt

Sets simulation time parameters such as playback speed, loop behavior, and clock steps.

```python
import datetime as dt
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import Clock
from czml3.types import IntervalValue, TimeInterval
from czml3.enums import ClockRanges, ClockSteps

start = dt.datetime(2024, 1, 1, 0, 0, 0, tzinfo=dt.timezone.utc)
end = dt.datetime(2024, 1, 2, 0, 0, 0, tzinfo=dt.timezone.utc)

# Document with clock settings for real-time playback at 60x speed
doc = Document(
    packets=[
        Packet(
            id="document",
            name="SimulationDocument",
            version=CZML_VERSION,
            clock=IntervalValue(
                start=start,
                end=end,
                value=Clock(
                    currentTime=start,
                    multiplier=60.0,
                    range=ClockRanges.LOOP_STOP,
                    step=ClockSteps.SYSTEM_CLOCK_MULTIPLIER
                )
            )
        )
    ]
)

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Create a Blue Semi-Transparent Box

Source: https://context7.com/stoops-ml/czml3/llms.txt

Constructs a CZML Packet for a Box primitive with specified dimensions, color, and outline properties. Requires Position and BoxDimensions.

```python
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import (
    Box, BoxDimensions, Color, Material, Position, SolidColorMaterial
)
from czml3.types import Cartesian3Value

# Create a blue semi-transparent box
packet_box = Packet(
    id="bluebox",
    name="Blue Box",
    position=Position(cartographicDegrees=[-114.0, 40.0, 300000.0]),
    box=Box(
        dimensions=BoxDimensions(
            cartesian=Cartesian3Value(values=[400000.0, 300000.0, 500000.0])
        ),
        material=Material(
            solidColor=SolidColorMaterial(color=Color(rgba=[0, 0, 255, 128]))
        ),
        outline=True,
        outlineColor=Color(rgba=[255, 255, 255, 255])
    )
)

doc = Document(packets=[
    Packet(id="document", name="box_example", version=CZML_VERSION),
    packet_box
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Construct and Export a CZML Document

Source: https://context7.com/stoops-ml/czml3/llms.txt

Defines a document with a clock and a satellite packet containing visual properties and interpolated positions, then serializes it to a JSON file.

```python
doc = Document(
    packets=[
        # Document preamble with clock
        Packet(
            id="document",
            name="Satellite Tracking",
            version=CZML_VERSION,
            clock=IntervalValue(
                start=start,
                end=end,
                value=Clock(
                    currentTime=start,
                    multiplier=60.0,
                    range=ClockRanges.LOOP_STOP,
                    step=ClockSteps.SYSTEM_CLOCK_MULTIPLIER
                )
            )
        ),
        # Satellite packet with all visual elements
        Packet(
            id="satellite_iss",
            name="ISS",
            availability=TimeInterval(start=start, end=end),
            billboard=Billboard(
                image="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAA0SURBVDhPY2RgYPgPxAwUACYYAwgYGBgYWKgFGBgYGBgZKUAZNUIDgE0NAwMD5gAAUhsH+cAAAAsQFklEQVRxJCYmJgYUBIMAKA8KA+IAgQAgICA",
                scale=1.5,
                horizontalOrigin=HorizontalOrigins.CENTER,
                verticalOrigin=VerticalOrigins.CENTER
            ),
            label=Label(
                text="ISS",
                font="12pt Helvetica",
                style=LabelStyles.FILL_AND_OUTLINE,
                fillColor=Color(rgba=[0, 255, 255, 255]),
                outlineColor=Color(rgba=[0, 0, 0, 255]),
                outlineWidth=2.0,
                horizontalOrigin=HorizontalOrigins.LEFT,
                verticalOrigin=VerticalOrigins.CENTER
            ),
            path=Path(
                show=TimeIntervalCollection(
                    values=[IntervalValue(start=start, end=end, value=True)]
                ),
                width=2.0,
                leadTime=2700.0,
                trailTime=2700.0,
                resolution=60.0,
                material=PolylineMaterial(
                    solidColor=SolidColorMaterial(color=Color(rgba=[0, 255, 0, 255]))
                )
            ),
            position=Position(
                interpolationAlgorithm=InterpolationAlgorithms.LAGRANGE,
                interpolationDegree=5,
                referenceFrame=ReferenceFrames.INERTIAL,
                epoch=start,
                cartesian=[
                    0, 4650397.56, -3390535.52, -4087729.48,
                    900, -567881.18, -828602.64, -6995188.66,
                    1800, -5308969.50, 2433751.75, -3985152.13,
                    2700, -5559191.47, 3636465.81, 2398566.73,
                    3600, -1092083.75, 1753068.15, 6739938.26,
                    4500, 4301545.02, -1619032.41, 5340730.82,
                    5400, 6028480.33, -3610312.82, -617627.59,
                    6300, 2619506.22, -2526553.46, -6052998.81,
                    7200, -3011438.35, 697635.55, -6357762.60,
                ]
            )
        )
    ]
)

# Output the complete CZML document
czml_json = doc.model_dump_json(indent=2, exclude_none=True)
print(czml_json)

# Write to file
with open("satellite.czml", "w") as f:
    f.write(czml_json)
```

--------------------------------

### Load a 3D Tileset

Source: https://context7.com/stoops-ml/czml3/llms.txt

Loads and displays 3D Tiles tilesets, suitable for large 3D datasets like city models or terrain, with options for show and maximum screen space error.

```python
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import Tileset

packet_tileset = Packet(
    id="tileset1",
    name="City Model",
    tileset=Tileset(
        uri="https://example.com/tilesets/city/tileset.json",
        show=True,
        maximumScreenSpaceError=16.0
    )
)

doc = Document(packets=[
    Packet(id="document", name="tilesets", version=CZML_VERSION),
    packet_tileset
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Create a Solid Colored Polyline

Source: https://context7.com/stoops-ml/czml3/llms.txt

Defines a polyline with a solid green color and a specified width. It uses 'clampToGround' to ensure the line follows terrain. Requires 'czml3'.

```python
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import (
    Color, Polyline, PolylineMaterial, PolylineDashMaterial,
    PositionList, SolidColorMaterial
)

# Create a solid colored polyline
solid_line = Packet(
    id="line1",
    name="Flight Path",
    polyline=Polyline(
        positions=PositionList(
            cartographicDegrees=[
                -75.0, 40.0, 0.0,
                -80.0, 35.0, 0.0,
                -85.0, 38.0, 0.0,
                -90.0, 42.0, 0.0
            ]
        ),
        width=3.0,
        material=PolylineMaterial(
            solidColor=SolidColorMaterial(color=Color(rgba=[0, 255, 0, 255]))
        ),
        clampToGround=True
    )
)

# Create a dashed polyline
dashed_line = Packet(
    id="line2",
    name="Dashed Route",
    polyline=Polyline(
        positions=PositionList(
            cartographicDegrees=[
                -100.0, 35.0, 10000.0,
                -110.0, 40.0, 10000.0,
                -115.0, 35.0, 10000.0
            ]
        ),
        width=4.0,
        material=PolylineMaterial(
            polylineDash=PolylineDashMaterial(
                color=Color(rgba=[255, 0, 0, 255]),
                dashLength=16.0
            )
        )
    )
)

doc = Document(packets=[
    Packet(id="document", name="polylines", version=CZML_VERSION),
    solid_line,
    dashed_line
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Create a Billboard with Base64 Image

Source: https://context7.com/stoops-ml/czml3/llms.txt

Generates a billboard marker using a base64-encoded PNG image. This is useful for embedding small images directly into CZML. Requires 'czml3' library.

```python
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import Billboard, Color, Position
from czml3.enums import HorizontalOrigins, VerticalOrigins

# Create a billboard with a base64-encoded PNG image
packet_billboard = Packet(
    id="facility",
    name="AGI Headquarters",
    position=Position(cartesian=[1216469.93, -4736121.71, 4081386.88]),
    billboard=Billboard(
        image="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4QIJCjEaAMQccAAAAB1pVFh0Q29tbWVudAAAAAAAQ3JlYXRlZCB3aXRoIEdJTVBkLmUHAAAANElEQVQ4y2P8////fwYKACNYwACJDBmysDAwMDCwkCqbjGBgYGBgZKSAYSM0ANjUMDAwYAYAAGQ3B/nVAAAAAElFTkSuQmCC",
        scale=1.5,
        horizontalOrigin=HorizontalOrigins.CENTER,
        verticalOrigin=VerticalOrigins.BOTTOM,
        show=True,
        color=Color(rgba=[255, 255, 255, 255])
    )
)

doc = Document(packets=[
    Packet(id="document", name="billboards", version=CZML_VERSION),
    packet_billboard
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Create a CZML Document with a Box Packet

Source: https://github.com/stoops-ml/czml3/blob/main/docs/user/examples.md

This snippet shows how to create a CZML document containing a packet that defines a blue box with specific dimensions and position. It requires importing necessary classes from czml3.

```python
from czml3 import Document, Packet, Preamble
from czml3.properties import (
    Box,
    BoxDimensions,
    Cartesian3Value,
    Color,
    Material,
    Position,
    SolidColorMaterial,
)
packet_box = Packet(
    id="my_id",
    position=Position(cartographicDegrees=[-114.0, 40.0, 300000.0]),
    box=Box(
        dimensions=BoxDimensions(
            cartesian=Cartesian3Value(values=[400000.0, 300000.0, 500000.0])
        ),
        material=Material(
            solidColor=SolidColorMaterial(color=Color(rgba=[0, 0, 255, 255]))
        ),
    ),
)
doc = Document(
    packets=[Packet(id="document", name="box", version=CZML_VERSION), packet_box]
)
print(doc)
```

--------------------------------

### Define Static and Cartesian Positions

Source: https://context7.com/stoops-ml/czml3/llms.txt

Illustrates creating static Position objects using cartographic degrees (longitude, latitude, height) or Cartesian coordinates (X, Y, Z).

```python
from czml3.properties import Position
from czml3.types import Cartesian3Value
from czml3.enums import InterpolationAlgorithms, ReferenceFrames
import datetime as dt

# Simple static position in degrees (longitude, latitude, height in meters)
static_pos = Position(cartographicDegrees=[-114.0, 40.0, 300000.0])

# Position using Cartesian coordinates (X, Y, Z in meters)
cartesian_pos = Position(cartesian=[1216469.93, -4736121.71, 4081386.88])

print(static_pos.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Define Cylinders and Cones in CZML

Source: https://context7.com/stoops-ml/czml3/llms.txt

Create cylindrical shapes by specifying length and radii. Cones are created by setting the top radius to zero.

```python
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import Color, Cylinder, Material, Position, SolidColorMaterial

# Create a cylinder
packet_cylinder = Packet(
    id="cylinder1",
    name="Communication Tower",
    position=Position(cartographicDegrees=[-100.0, 40.0, 200000.0]),
    cylinder=Cylinder(
        length=400000.0,
        topRadius=50000.0,
        bottomRadius=100000.0,
        material=Material(
            solidColor=SolidColorMaterial(color=Color(rgba=[0, 255, 255, 128]))
        ),
        outline=True,
        outlineColor=Color(rgba=[0, 0, 0, 255]),
        numberOfVerticalLines=16
    )
)

# Create a cone (cylinder with zero top radius)
packet_cone = Packet(
    id="cone1",
    name="Sensor Cone",
    position=Position(cartographicDegrees=[-110.0, 35.0, 300000.0]),
    cylinder=Cylinder(
        length=500000.0,
        topRadius=0.0,
        bottomRadius=200000.0,
        material=Material(
            solidColor=SolidColorMaterial(color=Color(rgba=[255, 0, 255, 100]))
        )
    )
)

doc = Document(packets=[
    Packet(id="document", name="cylinders", version=CZML_VERSION),
    packet_cylinder,
    packet_cone
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Define Ellipsoids and Spheres in CZML

Source: https://context7.com/stoops-ml/czml3/llms.txt

Create ellipsoids using radii dimensions. Spheres are created by setting equal radii for all axes.

```python
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import (
    Color, Ellipsoid, EllipsoidRadii, Material, Position, SolidColorMaterial
)

# Create a sphere (equal radii ellipsoid)
packet_sphere = Packet(
    id="sphere1",
    name="Location Sphere",
    position=Position(cartographicDegrees=[-120.0, 45.0, 100000.0]),
    ellipsoid=Ellipsoid(
        radii=EllipsoidRadii(cartesian=[100000.0, 100000.0, 100000.0]),
        material=Material(
            solidColor=SolidColorMaterial(color=Color(rgba=[0, 255, 0, 150]))
        ),
        outline=True,
        outlineColor=Color(rgba=[255, 255, 255, 255])
    )
)

# Create an ellipsoid
packet_ellipsoid = Packet(
    id="ellipsoid1",
    name="Coverage Ellipsoid",
    position=Position(cartographicDegrees=[-110.0, 40.0, 200000.0]),
    ellipsoid=Ellipsoid(
        radii=EllipsoidRadii(cartesian=[200000.0, 150000.0, 100000.0]),
        material=Material(
            solidColor=SolidColorMaterial(color=Color(rgba=[255, 128, 0, 100]))
        )
    )
)

doc = Document(packets=[
    Packet(id="document", name="ellipsoids", version=CZML_VERSION),
    packet_sphere,
    packet_ellipsoid
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Create a 3D model packet

Source: https://context7.com/stoops-ml/czml3/llms.txt

Defines a 3D model with specific orientation, scale, and silhouette properties.

```python
packet_model = Packet(
    id="aircraft1",
    name="Aircraft",
    position=Position(cartographicDegrees=[-75.0, 40.0, 10000.0]),
    orientation=Orientation(
        unitQuaternion=UnitQuaternionValue(values=[0.0, 0.0, 0.0, 1.0])
    ),
    model=Model(
        gltf="https://example.com/models/aircraft.glb",
        scale=100.0,
        minimumPixelSize=64.0,
        maximumScale=20000.0,
        show=True,
        silhouetteColor=Color(rgba=[255, 0, 0, 255]),
        silhouetteSize=2.0,
        runAnimations=True
    )
)

doc = Document(packets=[
    Packet(id="document", name="models", version=CZML_VERSION),
    packet_model
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Manage time-based properties

Source: https://context7.com/stoops-ml/czml3/llms.txt

Uses TimeIntervalCollection to define object visibility and property changes over specific time windows.

```python
import datetime as dt
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import Color, Point, Position
from czml3.types import IntervalValue, TimeInterval, TimeIntervalCollection

start = dt.datetime(2024, 1, 1, tzinfo=dt.timezone.utc)
mid = dt.datetime(2024, 1, 1, 12, tzinfo=dt.timezone.utc)
end = dt.datetime(2024, 1, 2, tzinfo=dt.timezone.utc)

# Object that's only visible during specific time windows
packet = Packet(
    id="sensor1",
    name="Ground Sensor",
    availability=TimeIntervalCollection(
        values=[
            TimeInterval(start=start, end=mid),  # Visible first half of day
        ]
    ),
    position=Position(cartographicDegrees=[-100.0, 40.0, 0.0]),
    point=Point(
        pixelSize=15.0,
        color=TimeIntervalCollection(
            values=[
                IntervalValue(start=start, end=mid, value=Color(rgba=[0, 255, 0, 255])),
                IntervalValue(start=mid, end=end, value=Color(rgba=[255, 0, 0, 255]))
            ]
        ),
        show=True
    )
)

doc = Document(packets=[
    Packet(id="document", name="time_demo", version=CZML_VERSION),
    packet
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Data Coercion with Pydantic

Source: https://context7.com/stoops-ml/czml3/llms.txt

Demonstrates czml3's use of Pydantic for automatic type coercion, converting numpy arrays and different numeric types to their correct representations.

```python
import numpy as np
from czml3.properties import Position
from czml3.types import Cartesian3Value

# Integer numpy array automatically converted to float
pos_from_numpy = Position(
    cartographicDegrees=np.array([-114, 40, 300000], dtype=int)
)
print(pos_from_numpy.model_dump_json(exclude_none=True))
# Output: {"cartographicDegrees": [-114.0, 40.0, 300000.0]}

# Lists converted to appropriate value types
cartesian = Cartesian3Value(values=[100, 200, 300])  # Ints become floats
print(cartesian.model_dump_json())
# Output: [100.0, 200.0, 300.0]
```

--------------------------------

### Define Polygons in CZML

Source: https://context7.com/stoops-ml/czml3/llms.txt

Create simple polygons or polygons with holes using the Packet and Polygon classes.

```python
simple_polygon = Packet(
    id="polygon1",
    name="Area Coverage",
    polygon=Polygon(
        positions=PositionList(
            cartographicDegrees=[
                -115.0, 37.0, 0.0,
                -115.0, 32.0, 0.0,
                -107.0, 33.0, 0.0,
                -102.0, 31.0, 0.0,
                -102.0, 35.0, 0.0
            ]
        ),
        material=Material(
            solidColor=SolidColorMaterial(color=Color(rgba=[255, 165, 0, 128]))
        ),
        outline=True,
        outlineColor=Color(rgba=[255, 0, 0, 255]),
        outlineWidth=2.0,
        height=0.0,
        extrudedHeight=100000.0
    )
)

# Polygon with a hole
polygon_with_hole = Packet(
    id="polygon2",
    name="Donut Shape",
    polygon=Polygon(
        positions=PositionList(
            cartographicDegrees=[
                -90.0, 40.0, 0.0,
                -90.0, 35.0, 0.0,
                -85.0, 35.0, 0.0,
                -85.0, 40.0, 0.0
            ]
        ),
        holes=PositionListOfLists(
            cartographicDegrees=[
                [-88.0, 38.0, 0.0, -88.0, 37.0, 0.0, -87.0, 37.0, 0.0, -87.0, 38.0, 0.0]
            ]
        ),
        material=Material(
            solidColor=SolidColorMaterial(color=Color(rgba=[0, 128, 255, 200]))
        )
    )
)

doc = Document(packets=[
    Packet(id="document", name="polygons", version=CZML_VERSION),
    simple_polygon,
    polygon_with_hole
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Define Colors with RGBA and RGBAF

Source: https://context7.com/stoops-ml/czml3/llms.txt

Colors can be specified using RGBA (0-255 range) or RGBAF (0.0-1.0 range) formats. Supports time-tagged color animations. Alpha defaults to maximum if not specified in RGBA.

```python
from czml3.properties import Color
from czml3.types import RgbaValue, RgbafValue

# Color using RGBA (0-255 range)
red_opaque = Color(rgba=[255, 0, 0, 255])

# Color using RGBAF (0.0-1.0 range)
blue_semi = Color(rgbaf=[0.0, 0.0, 1.0, 0.5])

# Color with shorthand list (alpha defaults to max)
green = Color(rgba=[0, 255, 0])  # Alpha will be set to 255

# Time-animated color (time, R, G, B, A pattern)
animated_color = Color(rgba=RgbaValue(values=[
    0, 255, 0, 0, 255,      # Red at t=0
    30, 0, 255, 0, 255,     # Green at t=30
    60, 0, 0, 255, 255,     # Blue at t=60
]))

print(red_opaque.model_dump_json(exclude_none=True))
# Output: {"rgba": [255, 0, 0, 255]}

print(blue_semi.model_dump_json(exclude_none=True))
# Output: {"rgbaf": [0.0, 0.0, 1.0, 0.5]}
```

--------------------------------

### Create a Rectangle

Source: https://context7.com/stoops-ml/czml3/llms.txt

Defines a rectangular region conforming to the globe's curvature using west, south, east, north coordinates and a solid color material.

```python
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import Color, Material, Rectangle, RectangleCoordinates, SolidColorMaterial

packet_rect = Packet(
    id="rect1",
    name="Region",
    rectangle=Rectangle(
        coordinates=RectangleCoordinates(
            wsenDegrees=[-110.0, 30.0, -100.0, 40.0]  # West, South, East, North
        ),
        material=Material(
            solidColor=SolidColorMaterial(color=Color(rgba=[0, 255, 128, 100]))
        ),
        fill=True
    )
)

doc = Document(packets=[
    Packet(id="document", name="rectangles", version=CZML_VERSION),
    packet_rect
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### CZML Document Output

Source: https://github.com/stoops-ml/czml3/blob/main/docs/user/examples.md

The resulting CZML document structure as a JSON array, representing the defined document and box packet.

```json
[
    {
        "id": "document",
        "name": "box",
        "version": "1.0"
    },
    {
        "id": "my_id",
        "position": {
            "cartographicDegrees": [
                -114.0,
                40.0,
                300000.0
            ]
        },
        "box": {
            "dimensions": {
                "cartesian": [
                    400000.0,
                    300000.0,
                    500000.0
                ]
            },
            "material": {
                "solidColor": {
                    "color": {
                        "rgba": [
                            0.0,
                            0.0,
                            255.0,
                            255.0
                        ]
                    }
                }
            }
        }
    }
]
```

--------------------------------

### Define a Corridor Geometry

Source: https://context7.com/stoops-ml/czml3/llms.txt

Corridors are shapes defined by a centerline and width that conform to the globe's curvature and can be extruded into volumes. Requires positions, width, and optionally height, extrudedHeight, material, outline, and outlineColor.

```python
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import Color, Corridor, Material, PositionList, SolidColorMaterial

packet_corridor = Packet(
    id="corridor1",
    name="Flight Corridor",
    corridor=Corridor(
        positions=PositionList(
            cartographicDegrees=[
                -120.0, 45.0, 0.0,
                -110.0, 40.0, 0.0,
                -100.0, 42.0, 0.0,
                -90.0, 38.0, 0.0
            ]
        ),
        width=200000.0,
        height=0.0,
        extrudedHeight=50000.0,
        material=Material(
            solidColor=SolidColorMaterial(color=Color(rgba=[0, 128, 255, 150]))
        ),
        outline=True,
        outlineColor=Color(rgba=[255, 255, 255, 255])
    )
)

doc = Document(packets=[
    Packet(id="document", name="corridors", version=CZML_VERSION),
    packet_corridor
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Define a Wall Geometry

Source: https://context7.com/stoops-ml/czml3/llms.txt

Walls are two-dimensional surfaces defined by a centerline that conform to the globe's curvature. They require positions, minimum and maximum heights, and can have optional material, outline, and outline color.

```python
from czml3 import CZML_VERSION, Document, Packet
from czml3.properties import Color, Material, PositionList, SolidColorMaterial, Wall

packet_wall = Packet(
    id="wall1",
    name="Boundary Wall",
    wall=Wall(
        positions=PositionList(
            cartographicDegrees=[
                -115.0, 50.0, 0.0,
                -112.0, 50.0, 0.0,
                -107.5, 50.0, 0.0,
                -102.0, 50.0, 0.0,
                -102.0, 45.0, 0.0
            ]
        ),
        minimumHeights=[0.0, 0.0, 0.0, 0.0, 0.0],
        maximumHeights=[100000.0, 150000.0, 200000.0, 150000.0, 100000.0],
        material=Material(
            solidColor=SolidColorMaterial(color=Color(rgba=[255, 0, 0, 128]))
        ),
        outline=True,
        outlineColor=Color(rgba=[0, 0, 0, 255])
    )
)

doc = Document(packets=[
    Packet(id="document", name="walls", version=CZML_VERSION),
    packet_wall
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```

--------------------------------

### Position Property Output with Coerced Types

Source: https://github.com/stoops-ml/czml3/blob/main/docs/user/examples.md

The output of the Position property after data type coercion, showing the coordinates as floating-point numbers.

```json
{
    "cartographicDegrees": [
        -114.0,
        40.0,
        300000.0
    ]
}
```

--------------------------------

### Create a Surface Ellipse

Source: https://context7.com/stoops-ml/czml3/llms.txt

Defines an elliptical area on the surface of the globe with customizable properties like semi-axes, rotation, material, and outline.

```python
from czml3 import Packet
from czml3.properties import Ellipse, Material, Position, SolidColorMaterial, Color

packet_ellipse = Packet(
    id="ellipse1",
    name="Coverage Area",
    position=Position(cartographicDegrees=[-100.0, 35.0, 0.0]),
    ellipse=Ellipse(
        semiMajorAxis=300000.0,
        semiMinorAxis=200000.0,
        rotation=0.785398,  # 45 degrees in radians
        material=Material(
            solidColor=SolidColorMaterial(color=Color(rgba=[255, 255, 0, 128]))
        ),
        outline=True,
        outlineColor=Color(rgba=[255, 0, 0, 255]),
        outlineWidth=3.0,
        height=0.0,
        extrudedHeight=50000.0
    )
)

doc = Document(packets=[
    Packet(id="document", name="ellipses", version=CZML_VERSION),
    packet_ellipse
])

print(doc.model_dump_json(indent=2, exclude_none=True))
```
Tokens:
Raw