CZML结构文档说明

CZML是JSON的子集，这意味着有效的CZML文档也是有效的JSON文档。具体来说，CZML文档包含一个JSON数组，其中数组中的每个对象文字元素都是CZML Packet。CZML数据包描述了场景中单个对象（例如单个飞机）的图形属性。

注意：即使在JSON技术上不允许使用注释，我们仍在这些示例中使用javascript注释。

[
    // packet one
    {
        "id": "GroundControlStation"
        "position": { "cartographicDegrees": [-75.5, 40.0, 0.0] },
        "point": {
            "color": { "rgba": [0, 0, 255, 255] },
        }
    },
    // packet two
    {
        "id": "PredatorUAV",
        // ...
    }
]

每个Packet都有一个id标识其描述对象的属性。ID不必是GUID，但它们确实需要唯一地标识CZML源中的单个对象以及加载到同一作用域中的任何其他CZML源。

如果id未指定，客户端将自动生成一个唯一的。但是，这会阻止以后的数据包引用该对象，以便例如向该对象添加更多数据。

除之外id，数据包还包含零个或多个（通常是一个或多个）属性，这些属性定义要绘制的与对象相关的图形项。在上面的示例中，我们指定了“ GroundControlStation”对象在WGS 84经度-75.5度，纬度40.0度和高度0.0米处具有固定的位置，并在其位置绘制了一个蓝色的Point。

为CZML定义了许多标准属性，包括用于在场景中添加 points, billboards, models, lines和其他图形的属性。可用属性在Packet页面以及链接的子属性和子类型页面上进行了详细说明。在此页面上，我们主要关注数据的结构。例如，我们描述了如何指定属性，以使其在两个不同的时间间隔内具有两个不同的值。

Intervals

在最一般的情况下，CZML属性的值是一个JSON数组，其中数组中的每个元素都是一个对象常量，用于定义该属性在不同时间间隔内的值。使用属性中的ISO8601间隔字符串指定数组中任何给定对象文字描述的间隔interval。

{
    "id": "myObject",
    "someProperty": [
        {
            "interval": "2012-04-30T12:00:00Z/13:00:00Z",
            "number": 5
        },
        {
            "interval": "2012-04-30T13:00:00Z/14:00:00Z",
            "number": 6
        },
    ]
}

在这里，我们someProperty在两个时间间隔内定义属性，第一个间隔是UTC从中午到1:00 PM（属性值是5），另一个时间间隔是从1:00 PM到2:00 PM UTC（属性值是6）当跨越两个间隔之间的边界时，该值将立即更改。number因为这是一个数字类型的属性，所以我们用来指示该值。一些属性（尤其是表示位置的属性）允许以多种格式指定值，例如笛卡尔X，Y，Z位置或制图经度，纬度，高度位置。每种类型的页面列出了每种属性支持的数据类型，以及每种属性所使用的值名称。

该interval属性是可选的。如果未指定，则假定该间隔跨越所有时间。指定多个无限间隔或通常重叠的间隔没有多大意义，但是如果您指定了此间隔，则在CZML文件或流中的后面一个优先。

在通常情况下，该属性的值仅在一个间隔上，间隔列表数组可以完全省略。

{
    "id": "myObject",
    "someProperty": {
        "interval": "2012-04-30T12:00:00Z/14:00:00Z",
        "number": 5
    }
}

与以前一样，interval如果该属性跨越所有时间，则可以将其省略。对于具有简单值的属性，例如上面显示的number属性，并且所有时间都具有单个值，可以更紧凑地给出该值：

{
    "id": "myObject",
    "someProperty": 5
}

该缩写表示法对于其值可以用一种简单的JSON数据类型（字符串，数字或布尔值）表示的任何属性均有效。

Composite Values

使用JSON数组表示更复杂的复合值，例如笛卡尔位置或颜色。对于笛卡尔位置，数组具有三个元素，分别对应于该位置的X，Y和Z分量。

{
    "id": "myObject",
    "someComplexProperty": {
        "cartesian": [1.0, 2.0, 3.0]
    }
}

即使在此间隔是无限的，也必须始终在一个间隔内指定复合值。如果将值[1.0, 2.0, 3.0]用作complexProperty直接值，则解释CZML的客户端有必要查看数组的内容以确定该数组是间隔列表还是单个值。因此，为简单起见，我们不允许这样做。

Sampled Property Values

到目前为止，我们已经讨论了如何始终为属性指定单个值，以及如何在不同的离散间隔内为属性指定不同的值。一些属性还允许您指定带有时间标记的样本，客户端将在这些样本上插值以在任何给定时间计算属性的值。时间是使用ISO8601字符串指定的。

{
    // ...
    "someInterpolatableProperty": {
        "cartesian": [
            "2012-04-30T12:00Z", 1.0, 2.0, 3.0,
            "2012-04-30T12:01Z", 4.0, 5.0, 6.0,
            "2012-04-30T12:02Z", 7.0, 8.0, 9.0
        ]
    }
}

在这里，我们指定该值为[1.0, 2.0, 3.0]中午，[4.0, 5.0, 6.0]一分钟后和[7.0, 8.0, 9.0]一分钟后。如果客户的当前时钟是中午30时，则该值将是[1.0, 2.0, 3.0]和[4.0, 5.0, 6.0]或之间的线性插值[2.5, 3.5, 4.5]。

为了简洁起见，也可以指定自某个时代以来的秒数。尽管这可能不如每次使用ISO8601字符串指定精度那样精确，但是当样本的时间少于一天或偏移量为秒总数时，通常这绰绰有余。

{
    // ...
    "someInterpolatableProperty": {
        "epoch": "2012-04-30T12:00Z",
        "cartesian": [
            0.0, 1.0, 2.0, 3.0,
            60.0, 4.0, 5.0, 6.0,
            120.0, 7.0, 8.0, 9.0
        ]
    }
}

最后，使用带时间标记的样本指定的属性具有一些其他可选的子属性，用于控制插值。

{
    // ...
    "someInterpolatableProperty": {
        "epoch": "2012-04-30T12:00Z",
        "cartesian": [
            0.0, 1.0, 2.0, 3.0,
            60.0, 4.0, 5.0, 6.0,
            120.0, 7.0, 8.0, 9.0
        ],
        "interpolationAlgorithm": "LAGRANGE",
        "interpolationDegree": 5
    },
}

在interpolationAlgorithm指定要使用的算法在从所提供的数据不同的时间内插的值。有关可能的值，请参见下表。该interpolationDegree属性指定用于插值的多项式的次数。如果未指定这些属性，则使用线性插值。有关与插值有关的属性的完整列表，请参见InterpolatableProperty。

每个样本的时间都不必落在包含该样本的时间间隔内，但是不会在其间隔之外使用这些样本。这对于通过更高程度的插值提供更好的精度很有用。

EventSource and Streaming

将整个CZML文档放在一个大JSON数组中，将很难以增量方式加载该文档。当今的网络浏览器允许在流完成之前对流进行一些访问，但是解析和解释不完整的数据需要缓慢而麻烦的字符串操作。为了促进高性能流传输，还可以使用现代浏览器的服务器发送事件（EventSource）API 来流传输CZML 。使用此API时，每个CZML数据包都作为单独的事件流传输到客户端：

event: czml
data: {
    // packet one
}

event: czml
data: {
    // packet two
}

结果，浏览器在接收到每个数据包时引发一个事件，其中仅包含该数据包的数据。这使我们能够以出色的性能逐步处理CZML数据。

到目前为止，我们可能已经隐含了使用单个数据包表示单个对象的情况，该数据包描述了与该对象关联的所有图形。但这并非一定如此。单个CZML流或文档可以包含具有相同包的多个数据包id，描述了同一对象的不同方面。

实际上，在某些情况下，两个数据包甚至可以描述一个对象的相同属性。当在多个时间间隔上定义属性或一个时间间隔包含许多带有时间标签的样本时，这很有用。通过将属性的完整定义分成多个数据包，我们可以更快地将相关数据输入Cesium，以最大程度地减少用户在Cesium开始渲染场景之前必须等待的时间。

当客户端收到CZML数据包时，它将遍历数据包中包含的每个属性。对于每个属性，它遍历定义该属性的每个时间间隔。对于每个间隔，它确定是否已经为属性定义了指定的间隔。如果已经定义了间隔，则更新现有间隔；否则，将更新现有间隔。否则，将创建一个新的。

更新现有间隔时，任何提供的子属性值都会替换现有值（如果有）。唯一的例外是，当先前的属性值和新的属性值都包含带有时间标记的样本时。在这种情况下，样本将添加到该间隔的样本列表中。

当新间隔与现有间隔重叠时，新间隔优先，并且现有间隔将被截断或完全删除。要牢记这一点很重要，因为在确定间隔是新间隔还是对现有间隔进行更新时，将针对截断的间隔测试较晚的间隔。

一个间隔中的采样必须通过增加单个数据包中的时间来排序。但是，在整个数据包中，没有必要以任何特定顺序提供样本。但是，在流传输非连续样本时必须注意确保合理的插值。

Availability

除该id属性外，CZML数据包还具有一个附加的特殊属性：availability。

{
    "id": "PredatorUAV",
    "availability": "2012-04-30T12:00:00Z/14:00:00Z",
    // ...
}

该availability属性指示对象的数据何时可用。如果已知某个对象的数据在当前动画时间可用，但是客户端尚未获得该数据（大概是因为它将在以后的数据包中到达），则客户端可以暂停并显示诸如“正在缓冲…等待接收数据。该属性可以是指定单个间隔的单个字符串，也可以是表示间隔的字符串数组。

如果以后的Cesium包更改或发现不正确，则可以更新此可用性。例如，SGP4传播器可能会一直报告可用性，但随后传播器会抛出异常，并且需要调整可用性。如果此可选属性不存在，则假定该对象一直可用。可用性范围仅限于特定的CZML流，因此两个不同的流可以为单个对象列出不同的可用性。在单个流中，为对象声明的最后一个可用性是有效的那个，并且忽略先前数据包中的任何可用性。如果某个对象一次可用，则客户端希望该对象至少具有一个属性，并且希望该对象当时需要定义的所有属性。如果对象没有任何属性

Extending CZML

可以使用自定义属性扩展CZML。为了最大程度地减少冲突，我们建议用户在其自定义属性前添加某种标识符。