vis_tools.CZMLWriter module#

CZMLWriter.py

This class simplifies the writing of Cesium CZML animation output files. It has methods for writing Vis-Tools-specific animations (migration and marker). Note that there are high-level methods on VisSet that implicitly create and use CZMLWriter so in many cases you will not need to directly instantiate/call this class yourself.

Usage:

writer = CZMLWriter()
writer.set_sim_duration(timestep_count)
writer.add_event_markers(my_event_recorder, my_demographics,
    "New_Infection", "Triangle", "red", "Top", 2)
writer.write(path.join(my_dir, "New_Infections.czml"))
class vis_tools.CZMLWriter.CZMLWriter(verbose=False)[source]#

Bases: object

Class for creating high-level visualizations in Cesium CZML format.

k_default_node_point_size = 8#
k_default_clock_multiplier = 14400#
k_default_migration_trail_duration = 86400#
k_default_migration_duration_days = 2#
k_default_migration_duration_seconds = 172800#
set_sim_dates(sim_start_date, total_timestep_count)[source]#

Set the sim start date and total timesteps.

These are required because all CZML layers are time-synced to the Cesium clock. It is possible to use set_sim_duration in lieu of this function.

Returns:

None

Parameters:

  • sim_start_date (date) – Start date for timestep 0

  • total_timestep_count (int) – Number of timesteps in simulation data

set_sim_duration(total_timestep_count, timestep_bounds=None, sim_start_date=None, emit_clock=True, anim_step_secs=None)[source]#

Set the sim duration and time range.

This function allows you to set the start date and total timesteps, but also allows emitting the CZML over a subrange of timesteps less than the number of timesteps in total_timestep_count. This is effective for trimming migration animations that would otherwise be too big down to a workable subset.

Returns:

None

Parameters:

  • total_timestep_count (int) – Total timesteps in sim

  • timestep_bounds – (list (start, end)): Timestep subrange for

  • animation –

  • sim_start_date (date) – Start date for timestep 0

  • emit_clock (bool) – Whether to emit a CZML Clock packet

  • anim_step_secs (int) – Clock multiplier for Clock packet

add_nodes(demographics, population_as_size=True, with_altitude=False, processor=None, namer=None)[source]#

Add demographics node data to the CZMLWriter object. DEPRECATED.

This (DEPRECATED) method allows you to add node representations to a CZML output file, where the node point size is relative to the node’s InitialPopulation. Since the Vis-Tools client does this in a much more flexible way, this method is deprecated, but may be educational for those looking to extend the CZMLWriter class.

Returns:

None

Parameters:

  • demographics (Demographics) –

  • population_as_size (bool) – True to scale point size by

  • InitialPopulation –

  • otherwise (fixed size) –

  • with_altitude – True to emit node coordinates including their

  • altitude (false to just emit them with default) –

  • altitude –

  • processor – None or a function that processes the node and and the

  • packet. (czml wrapper into a new CZML) –

  • namer – None or a function that converts a node into a name string

add_migrations(migrations, demographics, with_altitude=False)[source]#

Adds migration animations to a CZML output.

This function, given migrations in a particular format and demographics, adds “comet” animations for migration events.

Returns:

Number of infected human migrations in animation layer

Parameters:

  • migrations (obj) – An object that describes migrations (see below)

  • demographics (Demographics) – A Demographics object describing nodes

  • with_altitude – True to respect the altitude in the node coordinates

migrations is a dictionary where the keys are <timestep> and the values are objects with keys <from_node_id>-<to_node_id> and the values are the number of migrations at that timestep from from_node_id to to_node_id. See MigrationHelpers.py for more details.

add_vector_migrations(vector_migrations, demographics, migration_duration_timesteps, dot_color, dot_size_pixels, path_color, path_thickness_pixels, path_trail_time_factor)[source]#

Adds vector cohort migration animations to a CZML output.

This function, given vector migrations in a particular format and a demographics file, adds “comet” animations for migration events.

This function expects the following fields in vector_migrations:

  • Time (int): the timestep of the beginning of the migration event

  • FromNodeID (int): the node ID from which the migration emanates

  • ToNodeID (int): the node ID to which the migration completes

Returns:

Number of vector cohort migrations in animation layer

Parameters:

  • vector_migrations (CSVReport) – The ReportVectorMigrations.csv

  • report. –

  • demographics (Demographics) – The Demographics object describing the

  • nodes. (the trail length will be half the distance between the) –

  • migration_duration_timesteps (int) – The duration of the migration

  • timesteps. (animations in) –

  • dot_color (string) – A CSS #rrggbb color for the comet dot.

  • dot_size_pixels (int) – Size in pixels of comet dot.

  • path_color (string) – A CSS #rrggbb color for the comet tail.

  • path_thickness_pixels (float) – Thickness in pixels of comet tail.

  • path_trail_time_factor (float) – Length of trail as a multiple of

  • 1.0 (the migration_duration. E.g. if this is) –

  • will (the trail length) –

  • If (be the full distance from source node to the destination node.) –

  • 0.5 –

  • nodes. –

add_simplified_vector_migrations(vector_migrations, demographics, migration_duration_timesteps, arrow_color, arrow_thickness_pixels)[source]#

Adds vector cohort migration animations to a CZML output.

This function, given vector migrations in a particular format and a demographics file, adds “comet” animations for migration events.

This function expects the following fields in vector_migrations:

  • Time (int): the timestep of the beginning of the migration event

  • FromNodeID (int): the node ID from which the migration emanates

  • ToNodeID (int): the node ID to which the migration completes

Returns:

Number of vector cohort migrations in animation layer

Parameters:

  • vector_migrations (CSVReport) – The ReportVectorMigrations.csv

  • report. –

  • demographics (Demographics) – The Demographics object describing the

  • nodes. –

  • migration_duration_timesteps (int) – The duration of the migration

  • timesteps. (animations in) –

  • arrow_color (string) – A CSS #rrggbb color for the migration arrow.

  • arrow_thickness_pixels (float) – Thickness in pixels of comet tail.

add_event_markers(event_recorder, demographics, event_name, marker, color, placement, duration_days, with_altitude=False)[source]#

Adds event marker animation to a CZML output.

This function looks for a particular event in an event recorder report and emits an animation that puts a marker somewhere around the node and leaves it there for a specified period after the event.

Returns:

Number of event markers in animation layer

Parameters:

  • event_recorder (CSVReport) – Event recorder report object

  • demographics (Demographics) – Demographics object with node data

  • event_name (str) – Name of event to mark in the animation

  • marker (str) – Name of a marker icon (“Triangle” or “Cross”)

  • color (str) – Any HTML or SVG named color (e.g. “red”) or a CSS

  • string (color) –

  • placement (str) – Placement about the node point (“Top”, “Left”,

  • "Right") ("Bottom" or) –

  • duration_days (int) – Number of days for which the symbol should

  • fires. (remain about the node after it) –

  • with_altitude (bool) – True to set the symbol elevations to match

  • altitude (the node) –

  • otherwise. (or default altitude) –

add_weighted_network(demographics, network, gradient_spec, opacity_func)[source]#

Adds a weighted network visualization layer to a CZML output.

This method emits a CZML animation that provides a visual representation of a weighted network between nodes.

Returns:

Number of network segments added

Parameters:

  • demographics (Demographics) – Demographics object for nodes.

  • network (array) –

    array of objects:

    {
    from: <from-node-id>,
    to: <to-node-id>,
    weight: <float-weight>
}

  • gradient_spec (str) – gradient spec for a gradient with which to

  • lines. (color the network) –

  • opacity_func (function) – function(weight, norm_weight) that returns

  • [0 (the desired opacity in range) –

  • 1]. –

write_czml(file_path)[source]#

Write the CZML animation file.

Returns:

None

Parameters:

file_path (str) – The file path to which to write the CZML animation.

Raises:

I/O exceptions. –