Graphics & Visualization¶

The graphics module provides tools for visualizing DNA megastructures in both 2D and 3D.

PyVista 3D¶

3D visualization using PyVista to generate a video spinner.

crisscross.graphics.pyvista_3d ¶

rounded_polyline ¶

rounded_polyline(
    points, corner_fraction=0.45, samples_per_corner=16, uturn_angle_threshold_deg=170.0
)

Replace interior corners with fillets; handles three cases: - nearly-straight: pass-through - normal corner: quadratic Bezier fillet (A..P1..B) - near-180° (U-turn): generate a true semicircular arc across p1 Returns np.array((M,3)).

parallel_transport_frames ¶

parallel_transport_frames(points)

Compute tangent, normal, binormal at each point using parallel transport. Returns (tangents, normals, binormals) arrays same length as points.

build_swept_tube ¶

build_swept_tube(curve_pts, radius, n_sides=32, cap_ends=False)

Build a tube mesh by sweeping a circle along curve_pts using parallel-transport frames. Returns a pyvista.PolyData mesh.

create_graphical_3D_view ¶

create_graphical_3D_view(
    slat_array,
    slats,
    save_folder,
    layer_palette,
    cargo_palette=None,
    connection_angle="90",
    window_size=(2048, 2048),
    filename_prepend="",
)

Creates a 3D video of a megastructure slat design.

PARAMETER	DESCRIPTION
`slat_array`	A 3D numpy array with x/y slat positions (slat ID placed in each position occupied)
`slats`	Dictionary of slat objects
`save_folder`	Folder to save all video to.
`layer_palette`	Dictionary of layer information (e.g. top/bottom helix and colors), where keys are layer numbers.
`cargo_palette`	Dictionary of cargo information (e.g. colors), where keys are cargo types. DEFAULT: `None`
`connection_angle`	The angle of the slats in the design (either '90' or '60' for now). DEFAULT: `'90'`
`window_size`	Resolution of video generated. 2048x2048 seems reasonable in most cases. DEFAULT: `(2048, 2048)`
`filename_prepend`	String to prepend to the filename of the video. DEFAULT: `''`

RETURNS	DESCRIPTION
	N/A

Blender 3D¶

High-quality rendering using Blender, including the potential for animating the assembly of a crisscross megastructure.

crisscross.graphics.blender_3d ¶

look_at ¶

look_at(obj, target)

Points the provided object towards the target vector

PARAMETER	DESCRIPTION
`obj`	Blender object (typically a camera or light)
`target`	The target 3D vector

RETURNS	DESCRIPTION
	N/A

srgb_to_linear ¶

srgb_to_linear(c)

Convert an sRGB tuple (0–1) to linear RGB (0–1) for Blender.

create_slat_material ¶

create_slat_material(color, mat_name, metallic_strength=0.8, alpha_animation=False)

PARAMETER	DESCRIPTION
`color`	RGB color code (4-value, with the last value being the alpha).
`mat_name`	The name to assign to the material.
`metallic_strength`	How metallic the final material should be (default is pretty metallic). DEFAULT: `0.8`
`alpha_animation`	Set to True to enable alpha animation (for slat wipe-in animations). DEFAULT: `False`

RETURNS	DESCRIPTION
	The complete material object.

set_slat_wipe_in_animation ¶

set_slat_wipe_in_animation(
    frame_start,
    frame_end,
    slat_id,
    slat_cylinder,
    slat_center,
    slat_rotation,
    slat_length,
    hide_cube=True,
)

Sets up the animation for a single slat, which involves creating a cuboid and slowly covering the slat with the cuboid.

PARAMETER	DESCRIPTION
`frame_start`	The frame from which to start the animation
`frame_end`	The frame at which the animation ends
`slat_id`	The slat's name
`slat_cylinder`	The slat cylinder object pre-created in Blender
`slat_center`	The center of the slat
`slat_rotation`	The slat's orientation
`slat_length`	The slat's length
`hide_cube`	Set to true to hide the cover-cube from the viewport DEFAULT: `True`

RETURNS	DESCRIPTION
	N/A

set_slat_translate_animation ¶

set_slat_translate_animation(
    frame_start,
    frame_end,
    slat_cylinder,
    slat_center,
    slat_rotation,
    slat_length,
    extension_length=2.0,
)

Sets up a translation-based entry animation for a slat.

PARAMETER	DESCRIPTION
`frame_start`	The frame from which to start the animation.
`frame_end`	The frame at which the animation ends.
`slat_cylinder`	The slat cylinder object pre-created in Blender.
`slat_center`	The center of the slat.
`slat_rotation`	The slat's orientation.
`slat_length`	The slat's length.
`extension_length`	The distance that the slat will move to complete the animation. DEFAULT: `2.0`

RETURNS	DESCRIPTION
	N/A

check_slat_animation_direction ¶

check_slat_animation_direction(
    start_point,
    end_point,
    current_slat_id,
    current_layer,
    slats,
    animate_slat_group_dict,
)

Attempts a quick check to prevent slats from appearing 'out of thin air' but rather from a top/bottom support.

PARAMETER	DESCRIPTION
`start_point`	The current slat start position
`end_point`	The current slat end position
`current_slat_id`	The current slat ID (name)
`current_layer`	The slat's layer
`slats`	The dict of all slats in the design
`animate_slat_group_dict`	The dictionary of slat animation groups, in order

RETURNS	DESCRIPTION
	The new start and end position for the slat animation

interpret_cargo_system ¶

interpret_cargo_system(
    slats,
    layer_palette,
    grid_xd,
    grid_yd,
    slat_width,
    cargo_materials,
    frame_start=0,
    frame_end=0,
)

Interprets the cargo dict and places cargo stubs in the 3D scene, along with an animation if requested. Required to generate cargo cylinders.

PARAMETER	DESCRIPTION
`slats`	The dict of all slats in the design
`layer_palette`	Dictionary of layer information (e.g. top/bottom helix and colors), where keys are layer numbers.
`grid_xd`	The grid x-jump distance
`grid_yd`	The grid y-jump distance
`slat_width`	The width of the slat, used to determine the radius of the cargo cylinders.
`cargo_materials`	Dictionary of cargo materials, where keys are cargo types and values are the material objects.
`frame_start`	Animation start frame DEFAULT: `0`
`frame_end`	Animation end frame. If frame_start=frame_end, no animation will be added. DEFAULT: `0`

RETURNS	DESCRIPTION
	N/A

interpret_seed_system ¶

interpret_seed_system(slats, layer_palette, seed_material, grid_xd, grid_yd)

Interprets the seed array and places seed cylinders in the Blender scene. Makes the assumption that np.where can correctly figure out where each seed cylinder starts/stops. If there are errors here, this will need to be fixed.

PARAMETER	DESCRIPTION
`slats`	The dict of all slats in the design
`layer_palette`	Dictionary of layer information (e.g. top/bottom helix and colors), where keys are layer numbers.
`seed_material`	The material to use for the seed
`grid_xd`	The grid x-jump distance
`grid_yd`	The grid y-jump distance

RETURNS	DESCRIPTION
	N/A

create_graphical_3D_view_bpy ¶

create_graphical_3D_view_bpy(
    slat_array,
    slats,
    layer_palette,
    save_folder,
    cargo_palette=None,
    animate_slat_group_dict=None,
    animate_delay_frames=40,
    connection_angle="90",
    camera_spin=False,
    animation_type="translate",
    specific_slat_translate_distances=None,
    correct_slat_entrance_direction=True,
    force_slat_color_by_layer=True,
    slat_flip_list=None,
    include_bottom_light=False,
    filename_prepend="",
)

Creates a 3D video of a megastructure slat design.

PARAMETER	DESCRIPTION
`slat_array`	A 3D numpy array with x/y slat positions (slat ID placed in each position occupied)
`slats`	Dictionary of slat objects
`layer_palette`	Dictionary of layer information (e.g. top/bottom helix and colors), where keys are layer numbers.
`save_folder`	Folder to save all video to.
`cargo_palette`	Dictionary of cargo information, where keys are cargo types and values are dictionaries with color and other properties. DEFAULT: `None`
`animate_slat_group_dict`	Dictionary of slat IDs and the group they belong to for animation DEFAULT: `None`
`animate_delay_frames`	Number of frames to delay between each slat group animation DEFAULT: `40`
`connection_angle`	The angle of the slats in the design (either '90' or '60' for now). DEFAULT: `'90'`
`camera_spin`	Set to True to have the camera spin around the design DEFAULT: `False`
`animation_type`	The type of animation to use for slat entry ('translate' or 'wipe_in') DEFAULT: `'translate'`
`specific_slat_translate_distances`	The distance each slat will move if using the translate system. This should be in a dictionary format - not all slat needs to have the distance, only those that will be different from the default value of 2. DEFAULT: `None`
`correct_slat_entrance_direction`	If set to true, will attempt to correct the slat entrance animation to always start from a place that is supported. DEFAULT: `True`
`force_slat_color_by_layer`	Forces a slat to be colored by layer rather than by animation group (if animation is on). DEFAULT: `True`
`slat_flip_list`	List of slat IDs - if a slat is in this list, its animation direction will be flipped. This cannot be used in conjunction with the correct_slat_entrance_direction parameter. DEFAULT: `None`
`include_bottom_light`	Set to True to include a light source at the bottom of the design. DEFAULT: `False`
`filename_prepend`	String to prepend to the filename of the video. DEFAULT: `''`

RETURNS	DESCRIPTION
	N/A

Static Plots¶

2D graphics provided a quick assessment of a megastructure design.

crisscross.graphics.static_plots ¶

slat_axes_setup ¶

slat_axes_setup(slat_array, axis, grid_xd, grid_yd, reverse_y=False)

Prepares a matplotlib axis for slat plotting, making sure to extend limits to fit input deisgn.

PARAMETER	DESCRIPTION
`slat_array`	3D numpy array with x/y slat positions (slat ID placed in each position occupied).
`axis`	Axes to adjust.
`grid_xd`	X scaling factor for x values.
`grid_yd`	Y scaling factor for y values.
`reverse_y`	Set to true to reverse y axis (useful for side profile views). DEFAULT: `False`

RETURNS	DESCRIPTION
	n/a

physical_point_scale_convert ¶

physical_point_scale_convert(point, grid_xd, grid_yd)

Converts different grid scaling system into an actual 'physical' measure, w.r.t. distance between handles.

PARAMETER	DESCRIPTION
`point`	Input point (x,y) to convert
`grid_xd`	Scaling factor for x value
`grid_yd`	Scaling factor for y value

RETURNS	DESCRIPTION
	Scaled point (x,y)

points_per_data ¶

points_per_data(ax)

Return points-per-data-unit (x, y) for an axes, given current limits and layout. Make sure the figure is drawn before calling this (fig.canvas.draw()).

create_graphical_slat_view ¶

create_graphical_slat_view(
    slat_array,
    layer_palette,
    cargo_palette=None,
    include_seed=True,
    include_cargo=True,
    slats=None,
    save_to_folder=None,
    instant_view=True,
    filename_prepend="",
    connection_angle="90",
)

Creates a graphical view of all slats in the assembled design, including cargo and seed handles. A single figure is created for the global view of the structure, as well as individual figures for each layer in the design.

PARAMETER	DESCRIPTION
`slat_array`	A 3D numpy array with x/y slat positions (slat ID placed in each position occupied)
`layer_palette`	Dictionary of layer information (e.g. top/bottom helix and colors), where keys are layer numbers.
`cargo_palette`	Dictionary of cargo information (e.g. colors), where keys are cargo types. DEFAULT: `None`
`include_seed`	Set to True to include seed handles in the graphical view. DEFAULT: `True`
`include_cargo`	Set to True to include cargo handles in the graphical view. DEFAULT: `True`
`slats`	Dictionary of slat objects (if not provided, will be generated from slat_array) DEFAULT: `None`
`save_to_folder`	Set to the filepath of a folder where all figures will be saved. DEFAULT: `None`
`instant_view`	Set to True to plot the figures immediately to your active view. DEFAULT: `True`
`filename_prepend`	String to prepend to generated files. DEFAULT: `''`
`connection_angle`	The angle of the slats in the design (either '90' or '60' for now). DEFAULT: `'90'`

RETURNS	DESCRIPTION
	N/A

create_graphical_assembly_handle_view ¶

create_graphical_assembly_handle_view(
    slat_array,
    handle_arrays,
    layer_palette,
    slats=None,
    save_to_folder=None,
    connection_angle="90",
    filename_prepend="",
    instant_view=True,
)

Creates a graphical view of all handles in the assembled design, along with a side profile.

PARAMETER	DESCRIPTION
`slat_array`	A 3D numpy array with x/y slat positions (slat ID placed in each position occupied)
`handle_arrays`	A 3D numpy array with x/y handle positions (handle ID placed in each position occupied)
`layer_palette`
`slats`	Dictionary of slat objects (if not provided, will be generated from slat_array) DEFAULT: `None`
`save_to_folder`	Set to the filepath of a folder where all figures will be saved. DEFAULT: `None`
`connection_angle`	The angle of the slats in the design (either '90' or '60' for now). DEFAULT: `'90'`
`filename_prepend`	String to prepend to generated files. DEFAULT: `''`
`instant_view`	Set to True to plot the figures immediately to your active view. DEFAULT: `True`

RETURNS	DESCRIPTION
	N/A