Models, State and Commands

Models

To talk to CATMAID’s back-end, its API is used. To make this more convenient and provide extra functionality, some of these APIs are abstracted into front-end models, which are defined in the JavaScript files in the models sub-folder of the CATMAID library:

django/applications/catmaid/static/lib/catmaid/models/

The majority of the common front-end operations can be found in there. A typical function, like node creation, has a signature like this:

CATMAID.Neurons.create: function(state, projectId, x, y, z, parentId, radius,
    confidence, useNeuron, neuronName)

All back-end parameters are available plus a state object. This state is required as a safety measure to not accidentally change data that was already updated by someone else. The next section goes into more detail about that.

State

In a collaborative environment, clients can never be sure if the information they see is the most recent one. Therefore, some CATMAID APIs support state checks to prevent changes by a client that was not aware of changes done by another client. Such a state is sent along with the request created by our front-end models and consists of information about the node of interest and its neighborhood.

To represent the (local) state the client sees the world in, different state implementations can be used. The tracing layer, for instance, has its own implementation and undo/redo utilizes a much sparser representation. States provide access to nodes, their state information and special serialization methods. State information on various parts of a local node neighborhood can be represented in parallel. This allows for flexibility and granular access control. Information on individual nodes, their parents, children and links can be stored. Connectors are supported as well.

A complete node neighborhood state consists of the node, children, parent and links. A node state represents a node ID along with an edition time, a parent state encapsulates this information about a parent of a node. Then there is also a no chack state, which causes the back-end to disable state checking for a request.

Different actions require different states, below you find a list of stateful endpoints and what they expect. This list isn’t complete yet, some functions don’t support state checks, yet.

Operation	Required state
Delete node	Neighborhood state for node to node
Create node	Parent state for node append, else none
Insert node	Node state and children of edge
Move node	Node state
Edit node radius	Node state
Edit node confidence	Node state
Create connector	For initial links partner node states, else none
Delete connector	Connector neighborhood state
Update connector confidence	Connector node state
Update connector links	Connector and link state
Create/update/remove annotation	Node state
Create/update/remove tag	Node state
Change neuron name	Neuron state
Link connector	Node and connector state
Unlink connector	Node and connector state

Undo

Some of the user user actions are reversible, they can be undone and redone. Undoing a command is as simple as pressing Ctrl + Z. Alternatively, the history dialog accessible through the F9 key can be used, where redo can be selected as well. Actions that can be undone are listed below and CATMAID wraps these in so called commands. These maintain information about the applied changes and their inverse. This is a list of currently available commands and what their inverse operation is:

Operation	Inverse
Delete node	Create node, along with connectors
Create node	Delete node
Insert node	Delete node
Move node	Move node back
Edit node radius	Set original radius
Edit node confidence	Set original confidence
Create connector	Delete connector
Delete connector	Create connector and links
Update connector confidence	Set original confidence
Update connector links	Restore original links
Create/update/remove annotation	Delete/reset/create annotation
Create/update/remove tag	Delete/reset/create tag
Change neuron name	Set original name
Link connector	Unklink connector
Split skeleton	Block undo
Join skeletons	Block undo

Splitting and joining skeletons results at the moment in undo being blocked for this point in history. That is, commands executed before splitting or joining, can’t be undone for now.

Commands are typically defined in the same file as the model functions they wrap.