Client Library API

class blenderneuron.client.BlenderNEURON(h=None, ip='127.0.0.1', port='8000', show_panel=True, show_tutorial=True)

Bases: object

The BlenderNEURON client class, which sends commands to the server created by the BlenderNEURON Blender add-on

__init__(h=None, ip='127.0.0.1', port='8000', show_panel=True, show_tutorial=True)

Creates an XMLRCP client which will communicate with the server, shows the GUI panel, and the tutorial

Parameters:

• h – an optional NEURON “h” variable. If not passed in, the method will load NEURON automatically
• ip – the IP address of the machine where the Addon will listen to client commands. Localhost by default. If another machine is specified, make sure any firewalls allow communication. However, this may create a potential security issue as the port could be used to execute arbitrary commands while Blender is running. See: run_command()
• port – the port of the machine where the Addon will listen to
• show_panel – Shows the GUI window
• show_tutorial – Shows a short tutorial for how to use the client

clear_activity()

Removes collected activity values from all groups. Called at the start of simulation, using NEURON’s FInitialize() method.

Returns:None

collect_group(group_name)

Based on the group’s color level, gathers the values of the group’s collect_variable. This method is called at regular times during the simulation. See create_cell_group() for details.

Parameters:group_name – The name of the group whose section values to measure and store Returns:None

collect_section(section, group, recursive=True)

Recursively collects the section midpoint values of a group’s collect_variable (e.g. ‘v’)

Parameters:

• section – A root section of a group
• group – The group’s dictionary
• recursive – Whether to collect child section values (otherwise stop at root/soma)

Returns:

None

collect_segments_recursive(section, group)

Recursively collects the values of segments of a group cell (root section). Segments are given sequential 0-based names similar to NEURON cells and sections. For example, TestCell[0].dend[3][4] refers to first TestCell, 4th dendrite, 5th segment. Segment order is determined by the order in which they appear in NEURON’s xyz3d() function.

Parameters:

• section – A reference to a group root section
• group – reference to a group dictionary

Returns:

None

create_cell_group(name, cells, options=None)

Creates a cell group from a list of root sections. Each cell group can have different color and selection options.

Parameters:

• name – The name of the group of cells
• cells – a list of top level, “root” sections. The children of these sections will be exported
• options – The group can have the following options:

group[‘collect_activity’]: True/False, whether to collect the group section activity during simulation.

group[‘collect_variable’]: string e.g. ‘v’, the name of the section variable to collect.

group[‘collection_period_ms’]: int, e.g. 1, how often per simulator ms to collect activity 1=one datapoint per ms.

group[‘frames_per_ms’]: float, e.g. 2.0, how many Blender frames to use for each simulator ms.

group[‘spherize_soma_if_DeqL’]: True/False, whether to render sections that include “soma” in their names as spheres if their lengths and diameters are approximately equal.

group[‘3d_data’][‘color’]: 3-array, e.g. [1,1,1] for white, to specify the RGB values for the default color of all sections of the group.

group[‘3d_data’][‘interaction_level’]: one of “Group”, “Cell”, “Section” to specify the level at which sections of this group can be interacted with in Blender. “Group” creates one Blender object for the whole group, “Section” creates objects for each section. Use “Group” to maximize Blender performance, and “Section” to maximize debugging/interaction detail.

group[‘3d_data’][‘color_level’]: one of “Group”, “Cell”, “Section”, or “Segment” to specify the level at which sections of this group should be colored in Blender. The difference is visible only when cell activity is included. The chosen value will have the following effects:

Group: All sections will be colored based on the average value of collect_variable at the root sections of the group. Coarsest, fastest color method. Appropriate to visually approximate population level activity.

Cell: Sections of each cell will be colored based on the value at the soma(0.5) (root) section.

Section: Each section will be colored based on the value at the middle of each section.

Segment: Each section segment (h.n3d()) will be colored based on the value at that segment. The most detailed, most computationaly demanding color method. Note: if NEURON xyz3d() points are defined, a “segment” in BlenderNEURON refers to n3d()-1 points. However, if no xyz3d() points are defined, number of BlenderNEURON “segments” = nseg in NEURON.

BlenderNEURON will favor 3D point info over nseg when creating the Blender objects, however it will not alter the simulation. For example, if there are 10 3D points on a section, but nseg = 1, BlenderNEURON will show a 3D shape with 10 subdivisions, however all subdivisions will have the same color value because their values will come from the one compartment.

group[‘3d_data’][‘as_lines’]: True/False, whether to display sections as 0-diameter lines in Blender. Very fast, but will not render using Blender’s “Render” tab.

group[‘3d_data’][‘segment_subdivisions’]: int > 1. e.g. 3, the number of subdivisions to use when rendering the segment cylinder. If “smooth_sections” (see below) is False, use value of 1 to reduce the number of Blender polygons. If True, larger values result in smoother branching angles.

group[‘3d_data’][‘circular_subdivisions’]: int > 4, e.g. 8, the number of circular “sides” to use when rendering the segment cylinder. Larger values provide rounder cylinder shape, but result in more polygons.

group[‘3d_data’][‘smooth_sections’]: True/False: whether to render sections as smooth bezier curves, instead of straight lines. True results in more visually appealing morphology, but requires more polygons depending on the ‘segment_subdivisions’ value (above).

Returns:The created group dictionary

create_collector(group)

Greates a pair of NetStim and NetCon which trigger an event to recursively collect the activity of the group segments. This method does nothing if group[‘collect_activity’] is False

Parameters:group – The group dictionary for which to create the collector

static distance(a, b)

Returns the distance between two points defined as 2-lists/tuples

enqueue_command(command_string)

Asynchronous version of run_command

enqueue_method(name, *args, **kwargs)

Asynchronous version of run_method

gather_group_coords(group)

Recursively obtains the coordinates of all 3D points of the group sections

Parameters:group – the dictionary of the group Returns:None

get_along_coord_dim(dim, section, coord_i, along_start_coord)

get_cell_coords(section, result=None, spherize_if_DeqL=True)

Recursively gathers the list of coordinates of a cell (root section)

Parameters:

• section – A reference to NEURON root section
• result – None, used internally
• spherize_if_DeqL – Whether to create a sphere instead of a cylinder for sections with “soma” in their names and which have equal lengths and diameters (within 0.1 um)

Returns:

A list of dictionaries with section names, coordinates, and coordinate radii. Coords has the form of [x1,y1,z1,x2,y2,z2…], and radii [r1,r2,…]

get_coord_count(section)

Obtains the number of 3D points defined for a section. If no points have been added, uses NEURON’s define_shape method to automatically create them (will be equal to nseg).

Parameters:section – a reference to a NEURON section e.g. soma = h.Section() Returns:The number of 3D points the section has

get_coords_along_sec(section, along)

Gets the section 3d coordinate that is 0-1 fraction along from the begining of the section.

Parameters:

• section – reference to a NEURON section
• along – float, 0-1, refering to the fraction along the section

Returns:

a tuple of (x,y,z) coordinate

get_detail_level(cell_count)

Uses a heuristic to select an appropriate level of detail based on the number of cells in simulation

Parameters:cell_count – The number of “root” sections instantiated in NEURON Returns:One of “Group”, “Cell”, “Section”, or “Segment”

get_num_frames()

Computes the number of frames to be shown in Blender to represent the simulation.

It is equal to the maximum number of frames per ms of simulation x NEURON h.tstop

\(t_{stop}*\max_{0 \leq g \leq n}(fps_{g})\)

Returns:Number of animation frames

is_blender_ready()

Checks if communication with BlenderNEURON addon can be established at self.IP:self.Port

Returns:True if connection can be made, False otherwise

static point_line_distance(point, start, end)

prepare_for_collection()

Checks and creates a default group and its activity collectors

static rdp(points, epsilon)

Reduces a series of points to a simplified version that loses detail, but maintains the general shape of the series.

Ramer-Douglas-Peucker algorithm adapted from: https://github.com/sebleier/RDP

Parameters:

• points – An array of (x,y) tuples to simplify
• epsilon – The maximum distance that points can deviate from a line and be removed

Returns:

A simplified array of (x,y) tuples

refresh()

A convenience menthod that will recreate the default “all” group and recreate all connections. It should be called after NEURON model has changed (added/modified sections).

Returns:None

run_command(command_string)

Synchronously runs a Python command within Blender’s Python instance. This allows controlling/using Blender from NEURON/python.

Parameters:command_string – A python command. To include a return value, set a special variable ‘return_value’. Returns:None, but if return_value is set within the command, will return its value.

run_method(name, *args, **kwargs)

Synchronously requests and blocks while a BlenderNEURON addon method is executed in Blender

Parameters:

• name – The name of the BlenderNEURON addon method to call
• args – method parameters
• kwargs – This should be blank, as named parameters are not supported over XMLRPC

Returns:

The value returned by the BlenderNEURON addon method

send_activity()

Sends the collected group section/segment activity to Blender. The recorded activity values are compressed to remove co-linear points and are sent in batches to maximize performance.

Returns:

send_cons()

Gathers the start and end coordinates (if available) of all NetConn objects and sends them to Blender.

Returns:None

send_group(group)

Sends the 3d morphology data of a group to Blender

Parameters:group – Reference to the group’s dictionary

send_model()

A convenience method to send the model morphology, connections, and activity data to Blender. After this method executes, BlenderNEURON addon method ‘link_objects’ needs to be called for the cells to become visible in Blender. See: to_blender for details.

Raises:

Exception if communication with BlenderNEURON addon cannot be established

send_morphology()

Sends the cell morphology data of all defined self.groups to Blender

setup_default_connections()

Sets up all NEURON NetCon’s to be exported as synapses to Blender

setup_default_group()

Sets up all NEURON sections and their 3d coordinates to be exported to Blender

setup_defaults_if_needed()

Checks if there are any cell groups or connections setup for export to Blender, creates defaults if not.

See also:

setup_default_group setup_default_connections

shorten_name_if_needed(name, max_length=56)

Gets a shortened name string suitable for use as a name for an object in Blender.

Blender names must be <64 characters long If section name is too long, this method will truncate the string and replace it with an MD5 hash Also allows for up to 100,000 segments/materials per section

Parameters:

• name – The name of a NEURON object e.g. cell, group, section, segment
• max_length – The number of characters that will be kept before start of MD5 hash

Returns:

Same or, if necessary, shortened name string, suitable for use as Blender object name

show_panel()

Creates a NEURON window that shows the GUI widgets to perform basic model export operations

simplify_activity(times, activity)

Removes co-linear points from a time series of collected activity. Used to compress activity before sending to Blender.

Parameters:

• times – an array of times
• activity – an array of corresponding activity values

Returns:

times and activity arrays with the co-linear points removed

spherize_coords(sec_coords, length, steps=7)

Turns a cylindrical section 3D points into a 3D points of a sphere spanning the section length. This method assumes the section length and diameter are equal.

Parameters:

• sec_coords – A dictionary of section 3d coordinates. Same format as elements of array returned by get_cell_coords()
• length – The length of the section
• steps – The number of intermediate subdivisions to use to approximate the sphere. More steps uses more polygons but results in more smooth sphere.

Returns:

to_blender(color_unique_names=True)

A convenience method to send all groups of cells defined by self.groups property to Blender. The method first clears the Blender scene, sends the morphology, any activity, and NetConns, links them to the scene (shows), zooms out the camera to include all cells/sections, colors the sections based on their names, and sets the animation length based on h.tstop

If called without creating any groups, it will create a default “all” group which contains all sections instantiated in NEURON

Parameters:color_unique_names – Whether to color the cell sections based on their names, gray otherwise Returns:None

static update_group(group, options)

Updates a dictionary with another dictionary, replacing values of matching keys

Parameters:

• group – dictionary to update
• options – dictionary with which to update the first dictionary

Returns:

an updated first dictionary

wait_till_blender_is_ready(timeout=10)

Blocks the thread while waiting for communication with BlenderNEURON addon for up to timeout seconds.

Raise:Exception if Blender server was not ready before the end of the timeout