Models, State and Commands


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:


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.


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


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.