How to Omni
Quick Guide to Getting Started
Noobie Guide To Getting Started
Playing Omni Task Selector Style
Left Hand Side Task Selector Buttons
Crashes, Core Dumps and Freezes
Notes on Freezes Crashes and Core Dumps
Omni is the name of a program that we use for reconstructing three dimensional objects. In the Seung Lab, we use Omni to construct neurons (a type of brain cell) and neurites (pieces of neurons). During the reconstruction of a neuron or neurite you will often face many challenges. This guide will highlight common challenges, suggest solutions, and work as a reference for general help.
After Omni is open, begin tracing by left clicking the ‘cursor’ button (referred to on the Top Buttons list). Then you will left click either the ‘two rectangles’ - one light blue with a smaller rectangle on top of it that’s yellow, or the ‘multicolored square’ (referred to on the Top Buttons list). (The difference here is whether you want to see all three 2D image windows or just the highest resolution 2D image window.) Once you’ve opened the 2D/3D setup you like you will left click segmentation1 (referred to on the Left Hand Side Buttons list). With the segmentation list open the next step is to set a threshold(s) you think appropriate. Go to the Global Threshold (referred to on the Right Hand Side Buttons list) and change the 0.999 to a number below zero you think best for the project you’re working on. (In general we test out different threshold for each set). Next you will change the Auto Spread Threshold (referred to on the Right Hand Side Buttons list) to something less than the Global Threshold. This will give you the option of growing any branch of a neuron with greater speed.
A set up that works in most cases will be: GT (Global Threshold) set to 0.750 - 0.600 and a AST (Auto Spread Threshold) set to 0.350 - 0.500.
Once you’ve set up you will begin working on the set. To work on a set typically means to reconstruct all the neurons and neurites of a given volume. We use typically here because sometimes you will be doing more specific tool testing or other such tasks - like troubleshooting.
If you are just doing a regular Omni task then you will begin the construction, the joining and the validation of all the segments on your working list. Left click the segment with the largest Total Size on the Working Tab list (referred to on the Left Hand Side Buttons list). The segment will appear in the 3D view. If it doesn’t appear left click on the 3D and hit the letter ‘C’ on your keyboard and it should center your ‘view point cross hair’ on the selected segment. You can now begin tracing your segment looking for missing branches, pieces, spines, nubs, dust, and mergers. Once you finish tracing the segment you are working on you will ‘Join All’ by left clicking ‘Join All’ (referred to on the Right Hand Side Buttons list) or by hitting ‘J’ on your keyboard. After you have joined everything together you will validate everything by left clicking ‘Valid’ (referred to on the Right Hand Side Buttons list) or by hitting ‘V’ on your keyboard. When you validate the segment(s) it will move segment(s) into the Valid Tab (referred to on the Left Hand Side Buttons list). You can change between tabs to see all the Valid segments you’ve made and all the Working Tab segments you have left to validate. Every time you validate a segment the percentage bar at the very bottom (referred to on the Left Hand Side Buttons list) will fill up a little bit more. Once you validate all the segments in the Working Tab you will be at 100% and finished with the task.
To BE Continued
Turn on an operational workstation. Press the silver horizontal diamond shaped power button, with the power symbol engraved on it, if you are using the black rectangular Alienware machines. The button is located above the Alienware symbol (Alien head), and near the USB ports in the front face of the machine. When using the triangular Alienware machines the power button is on the front facing angle of the machines. The power button is the alien head in this case, and on this case. =P
Omni runs on the operating system called Ubuntu. Ubuntu is the default operating system on our machines. We have both windows and Ubuntu on all machines. Too boot a machine into Windows there are some steps. First you must get to the boot menu. This can only be done while a machine is turning on - otherwise it will boot automatically the the default operating system. After the power button has been pressed and the computer begins to power on, you will have a short amount of time to access the boot menu. Hit the F12 key on your keyboard when prompted during the startup process. The F12 key is located above the Backspace on the right hand side of the keyboard. If you want to make extra sure you hit the small time gap where the boot menu is accessible, hit the F12 key repeatedly for about 10 seconds during the startup process. This will insure that you hit the key at the right time.
Once you get to the boot menu there will be a black screen with white letters. There will be a list of three available boot options: Ubuntu, Windows, Ubuntu (something else). Choose which one you desire and the computer will boot to the selected operating system. (Stick with plain Ubuntu or windows.)
You have reached the login screen of the Ubuntu operating system. Now you will select your username from the list of usernames on the left hand side of the screen. You can use the mouse to left-click on the appropriate username, or you can use the arrow keys to scroll up and down through the available usernames. Once you found the username you want to use, type in your password and hit the Enter key. If you keep getting login errors check to see if the Caps Locks key is on. You can check by looking on your keyboard at the top right hand corner. If the middle symbol, that looks like the letter ‘A’ with a box around it, is lit up in green light (or any other color) then the Caps Lock is on. To disengage the Caps Lock you will toggle (press) the Caps Lock key. The Caps Lock key is located on the left hand side of the keyboard between the Shift key and the Tab key.
Congratulations! You’ve made it to the desktop. Ubuntu (AKA Linux) might be different than the typical operating systems you usually use (Windows, Mac OS). No need to be afraid. Ubuntu is an awesome OS (operating system) and with a little time and effort, your learning will be rewarded.
Most of our computers data isn’t stored locally. This means that the majority of the data we will be accessing is stored on the cloud. Mounting the data enables us to interact with the cloud. Thus, because Omni is located on the cloud we need to mount the data before we can open Omni. To mount the data we need to open a terminal.
The hot keys shortcuts to open a terminal are: Hold down Alt and Ctrl, then hit the letter ‘T’. You can also click the Ubuntu Icon on the top left hand side in the hot bar to search for Terminal. Clicking the Ubuntu Icon will bring up a search window. Type Terminal in the search bar. As you type it will search and find a black box icon with the characters ‘<_’ - no spaces (without quotations).
After running Terminal a medium sized black box with some text will appear. In this black box you will type the word ‘Mountlab’ - all one word (without quotations). This will prompt you to enter your “Logging Into The Computer” password. You won’t be able to see the characters you are typing when typing the password - for security reasons. Once you believe you have typed your password correctly you will hit the Enter key.
The next step is to type in a series of passwords very much like you did in step one. The only difference here is the password. The password you need to type will be your Princeton Email Password. Your Princeton email is the one that ends in @princeton.edu. If you do not yet have an Email Password (or a Princeton email) you can ask someone else in the lab to mount the data for you. If you do have an Email Password you will go ahead and type it in and hit the Enter key. You will be prompted another time to enter another password. This will also be your Princeton Email Password. Enter your password again and hit the Enter key. You will be prompted one last time. Again, this will be the Princeton Email Password. Enter your password again and hit the Enter key. (If you are wondering, each time you type in your password and you enter it you are gaining access to a new directory.) Congratulations, you have mounted the data!
If you get any errors mounting the data check the Caps Lock key and try again. Opening a new Terminal is also good for troubleshooting.
In order to open Omni we will be using the Terminal (The black box thing) from before. If you have trouble with the Terminal that you were using before, you can always open a new one. To run Omni from the terminal you will type ‘omni’ - all one word (without quotations (lowercase ‘o’)). Once you input the command a window will pop up. It will be a white window with Omni, Login and Task at the top. It is important to note that once you open Omni, if you close the terminal you ran it from, Omni will close.
While selecting the Omni window bring your mouse cursor up to the top of the monitor that you have the Omni window in. You should see a gray bar drop down that has some drop down choices. If you can’t get the bar to drop down try moving your mouse cursor to the top of the other monitor(s) to get the same effect. Depending on which window is selected in Ubuntu the drop down menus will be specific to that window. If it still won’t appear try moving the Omni window from fullscreen to window mode. This can be done by holding left click and dragging the gray bar at the top of the Omni window.
Once you get the menu to drop down you’ll see these options: File, Edit, Project, Tools, Window, Help. To open an Omni file you will left click the File button. Another drop down menu will appear and your choices will be: New Project…, Open…, Close, Save, (A list of recent files that have been opened), Quit.
When opening a file for the first time (a file that isn’t on the recent list) you will left click Open… . This will bring up a white window with a list of Directories (a file that consists solely of a set of other files ((which may themselves be directories)), a search bar and a few other buttons. Ninety Nine percent of the time when opening an Omni file you will open the folder labeled, ‘seungmount’ - all one word (without quotations). Then you will open the folder labeled ‘Omni’ - (without quotations). Then you will open the folder labeled ‘TracerTasks’ - all one word (without quotations). Then you will open a more specific folder for the task at hand. Someone will help you find the folder/file you need from there. An example of an Omni file would look something like this: ‘omnidata/e2198/e2198_gs_12_f_104.omni’ - all one path (without quotations).
To log into Omni you will left click the the Login button on the top left of the newly opened Omni window. A small window will pop up. In the window there will be three boxes: Endpoint, Username, Password. The endpoint, if not already set, should be set to http://eyewire.org. The Username should be your Eyewire Username. Your Password should be your Eyewire Password. After you type the information in the correct fields and you hit the Enter key, you will be transported to a larger window called the Task Selector.
By logging into Omni you will have access to the Task Selector. The Task Selector is used for training and work. In the Task Selector you will see a list of tasks, some drop down menus, and a search bar. Each task will have its own unique values in each of the columns: ID, Cell, Parent, Weight, % Percent, Path, Users, and Notes. The ones you need to pay attention to typically are Users and Notes. Before selecting a task you will double left click on the Notes box in the same row as the task want. Once the cursor appears you will type your name so other Tracers will know who is working on that task. Then to start doing the task you left click Trace in the bottom left hand corner of the window. (In some cases we want to limit the amount of people on each task. If a Tracer adds a note to a particular task then we know who is on the task at that time.)
After Omni is open, begin tracing by left clicking the ‘cursor’ button (referred to on the Top Buttons list). Then you will left click either the ‘two rectangles’ - one light blue with a smaller rectangle on top of it that’s yellow, or the ‘multicolored square’ (referred to on the Top Buttons list). (The difference here is whether you want to see all three 2D image windows or just the highest resolution 2D image window.) Once you have the 2D and 3D open left click the 3D and hit ‘C’. This will center the axis on your seed piece. Then to make sure it’s the seed piece you actually want (there is a bug where the seed piece is wrong from the start) you will deselect it with Ctrl + Shift + right click. After it is deselected you will know because the 2D will show all the segments colors. This tells you there are no selected segments. Once you are here you will hit the ‘Seed’ button. If the same seed piece comes up that’s a good sign. If a different seed piece comes up that’s a good sign too. From here if you want to make ultimately sure that you are on the seed piece you need you can do one more thing. First deselect the segment(s) you have up like you did before. Once you’ve deselected, go to the search bar (referred to on the Left Hand Side Buttons list) and type in the number next to the ‘Seed’ button (referred to on the Left Hand Side Task Selector Buttons list) and hit the Enter key. This will bring up your seed piece and you can begin tracing.
The objective of the comparison process is to bring an unbiased view to the tracers work and correct it’s errors. (Sometimes you will do your own comparison jointly with another tracer.)
Compare is a button we have in the Task Selector that is used to check two tracers’ work at the same time. The ‘Compare’ button is located next to the ‘Trace’ button in the bottom left hand side of the Task Selector window. To compare a task you will highlight it by left clicking the row it is in and then left clicking the ‘Compare’ button.
This will bring up the normal Task Selector Omni UI (User Interface). The only difference will be the buttons near the ‘Seed’ button (referred to on the Left Hand Side Task Selector Buttons list).
There will be 1 or more new buttons depending on how the tracers did the task. There could be buttons like: All, 100%, Username: %, and a new ‘Seed’ button that says Seed: %. The ‘Username: %’ button means, that user didn’t add the % of stuff that is next to their name. For example: Ben: 30%. This means that Ben didn’t add 30% of what the other tracers added. ‘All’ shows all things added. ‘Seed:%’ is still acts as the normal ‘Seed’ button.
If you are doing a comparison your job is to deem which segments are correct and which are incorrect. Once you have done so you will deselect all segments that you think aren’t correct (leaving the correct ones). And hit the ‘Done’ button (referred to on the Left Hand Side Task Selector Buttons list)
When you open an omni file or task for the first time you’ll notice many windows and buttons. Most of them you will never interact with... on purpose =P . There are key ones to note, but before that here are all the buttons, doodads and fixtures.
From right to left: Save Disk that looks like an old floppy disc, the hand, the cursor or mouse, paint brush, eraser, fill bucket, star, scissors, big ‘A’ little ‘a’, thumbs up, a black dead plant looking thing or a bundle of droopy arrows (Related to the Auto Spread), a window with a green plus, two rectangles one light blue with a smaller rectangle on top of it that’s yellow, a multicolored square, Alpha Level, Fade To Black, a pallet in a box, mysterious light blue wispy thing in a box, Login, Task.
Top Buttons to note:
Cursor, a multicolored square, a black dead plant looking thing or a bundle of droopy arrows
From Top to Bottom: A medium size box with four columns that say enable, Name, ID, Notes. Within the box it says segmentation1 and channel1. These two can be toggled on and off with the left click.
If you don’t already see a larger vertical long box, left click segmentation1 in the medium sized box.
You will see a large vertical box appear with several tabs. The tabs include: Working, Valid, Uncertain, Recent. The box has columns and rows. The columns say: ID, Num Pieces, Total Size. This box of columns and rows gives you specific information on each segment you have in your volume.
Under the columns and rows you will see the text ‘Page’, and a few buttons. (Page has a small box that indicates what page you are on in whatever tab you have selected in the vertical box.) After the backslash ‘/’ you will see the total number of pages in that tab.
The next four buttons, continuing down, navigate through the pages: |<< , < , > , >>|. The double arrow with a line brings you to page one or the last page. The single arrows navigate one page forward or backwards. If you want to go to a specific page you can enter the number in the small box next to the text that says ‘Page’ and hit the Enter key.
Beneath the arrows and ‘Page’ text there is a blank horizontal search bar. In this bar you can search for a specific segment or segments by typing in their ID number(s). If you want to search multiple at once you need to add a comma after each ID number, i.e. 549199, 455854, 474493 (spaces between them are optional). These next numbers have a hyphen in the middle of them which will make the search illegal. i.e. 549-199, 455-854, 474-493. Take the hyphens out and you should be good (see previous string of numbers).
And lastly on the left hand side we have at the very bottom a bar that slowly fills up as you validate things in the working list (we will get to what validating things does in another section). Next to the bar on the right is a 0.0%. This indicates how much of the data you have validated in the set you are working on.
Left Hand Side Buttons to Note: Segmentation1, Working Tab, Valid Tab, Page Numbers
On the top right hand side where it says Tools we have two bars. Inside them there is a number 0.999. They are labeled Global Threshold and Auto Spread. They are titled: Graph Tools, subtitled Minimum Affinity to Join.
Below the thresholds are five buttons clustered together labeled: Join, Join All, Split, Break[a][b].
Under that there is another cluster of buttons titled, Validation Set Selected Segments.. . Below the title there are buttons labeled: Valid, Uncertain, Not Valid, Not Uncertain, Show Validated.
Just below that are two check circles labeled: In Color and As Black.
Below that there are three X,Y,Z bars titled Display Tools and below them a button labeled Save Location.
Finally there is a section titled Annotations with a button labeled Show Annotations and just under, a box with the columns: Comment, Position, Size.
Right Hand Side Buttons to Note: Join All, Split, Shatter, Join, Valid, Global Threshold, Auto Spread
On the left hand side, when using the task selector, it says ‘Inspector’. Below that we have a box that has two tabs: Task and Volumes. In the Task Tab we have Cube ID, Cell ID and a box that is the ‘Notes’ section from the Task List. (It can be edited while inspecting a task also.) Below that we have a button that says ‘Seed #’ (the hashtag/pound symbol will be the number of the seed piece you should start from to complete the task. Underneath that and finally we have two buttons: Skip and Done. If you no longer wish to work on a task you can skip it without submitting it. If you are finished tracing you can hit done and it will bring you back to the task selector. In the Volumes Tab we have four columns” Enable, Name, ID, Notes. This tab is similar to the box (referred to in the Left Hand Side Buttons list).
Left click either the two rectangles - one light blue with a smaller rectangle on top of it that’s yellow, or the multicolored square (referred to on the Top Buttons list). Doing so will open the 3D and 2D views. If you clicked the multicolored square you will get three 2D views and one 3D view. All 2D views have two tabs on the bottom of each window. First the tab is labeled channel1 -- then either XY View, XZ View, or ZY View. The Channel1 tab is an EM (Electron Microscopy) image. The XY View usually has the best resolution. This is due to how the images were made. The second tab is labeled segmentation1 -- then either XY View, XZ View, or ZY View. This tab is for looking at the segments without the EM view inhibiting distinction between EM borders. Each window has in the top right hand corner two buttons. The ‘X’ closes the tab you were viewing and the ‘two rectangles’ pop the view out so you can move it around. In the three 2D views there are four lines of text and numbers in the bottom left hand corner: Level, Zoom Factor, # - #, Tiles. The two hashtags separated by a hyphen are representing numbers that will be different in every volume. This info is good for making notes specific to a slide.
There are a few hidden things you can do in Omni that can be very useful to know. One of them is the ability we have to right click on a segment and bring up the dropdown menu. This drop down menu has a list: Segment “ID” (Root “ID”), Not Valid in segmentation1, Select Only This Segment, Deselect Only this Segment, Randomize Root Segment Color, Randomize Segment Color, Set Segment Palette Color, Join ALL Selected Segments, Join This Selected Segment with… , Split Segments, Cut Segment(s), Set Segment Valid, Set Segment Not Valid, Properties, List Children.
Randomize Segment Color, and the segment ID. These are good for some quick changes and useful information. You can also pick a specific color for a segment if you choose ‘Properties’ and then left click the orange button.
There are many minor errors here and there that you’ll find. Please take note of them. Try to remember what you were working on and what actions you took leading up to the error. This information can help to fix these problems in the future and would be appreciated greatly.
Omni doesn’t autosave in the typical sense. The way autosaves works is by saving what you ‘Join’ and ‘Split’. Thus, if while working on a segment/object/supervoxel of a neuron or neurite, and Omni happens to crash/core dump/freeze, anything you haven’t joined together or split apart will disappear - and when upon re-opening Omni all else will be essentially lost.
In order to protect yourself from crashes, core dumps, and freezes we suggest you periodically ‘Join All’ when you think you have traced a decent amount of correct segments/objects/supervoxels. This a kind of work-around-autosave will help cut your losses when Omni eventually breaks down.
Omni tends to crash often for lots of reasons, some unknown at this time. A Core Dump is a kind of crash we often see when there is some kind of problem with the memory or files. Omni often freezes at times. There are two kinds of freezes we have seen so far. The first kind is when Omni stops responding and begins to fade to black and white grayscale colors (it's a graphical way of telling you that the application is stalling). The second is when Omni stops responding and looks kinda normal.
During some kinds of freeze you can’t close Omni the conventional way and it requires ‘htop command’. The ‘htop command’ is very much like the Task Manager in Windows or Activity Monitor on Mac. To use the ‘htop Command’ you will open a new Terminal and type ‘htop’ - all one word (without quotations). This will bring up a window with two lists. In the bottom you will see a list of programs. To close Omni you will select Omni from the list with either left click or the arrow keys. Finding Omni on the list can be a little difficult if you’ve never done it before. Look in the VIRT column for something with red numbers and many gigabytes. If you can’t find that you can look at the Command column and find ‘Omni’ - all one word (without quotations). Once you have Omni selected you will hit F9 on the keyboard. F9 is located above the Backspace Key in the middle of the keyboard. After you hit F9 you will hit the Enter key to verify that you want to close it.
For the other types of freezes usually you can quit the regular way. If that doesn’t work you can always close the terminal. And if that still doesn’t work you can use the steps from the previous paragraph.
It’s important to note in the cases of freezes, crashes, and core dumps that saving as you go and ‘Joining’ as you go will help to mitigate the data loss and help to ameliorate some the the stress. Also sometimes when Omni freezes it will unfreeze if you wait a minute or two. Also sometimes if you move the Omni window around, minimize or maximize or switch screens, it will unfreeze Omni. (Though this is less likely the case.)
Omni has different combinations of similar hotkeys that do very different things. For a list of hotkeys refer to the Omni Hotkeys section.
For example: Ctrl plus right clicking on a segment in 2D/3D will deselect all other segments except the one you are clicking. When in a very similar situation, Ctrl plus Shift plus right click on a segment in 2D/3D will deselect only the segment you are clicking on. Thus, when you are still getting a hand on Omni controls you will accidentally deselect everything and this can be disconcerting.
When this happens hit Ctrl plus ‘Z’ and it will bring up a small window asking if you would like to undo the previous action. Left click the ‘Yes’ button or hit the ‘Y’ key (for a short cut) to complete the undo sequence.
Static Crosshair size
Save camera vantage point
Get rid of dark colors available in random colors
When in Auto Spread mode left click to rotate object doesn’t work when left clicking an object
Ctrl + Shift + Right click has the ability to add segments as if you were Left clicking in Cursor mode
Task Selector doesn’t remember your window size.
Cursor, Windows, and segmentation1 should have an option to have them auto selected when starting a task or project. (Most useful in Task Selector mode)
Saving seconds by automating cursor, 3D/2D, keeping threshold, task selector window remembering size.
Hitting Enter when typing in a note on task selector will delete note the first or second time hitting enter. Once you click on something else after typing your note the notes section saves it and enter can be used to alter it. Even clicking sometimes doesn’t work
Having to go in to hit ok slows us down: a way to hit done comparison in the task selector window
To BE Continued
Seung Lab
[a]Now apparently called "MultiSplit".. Oh wait, maybe "Shatter"? I also see another button not mentioned here that's labeled "Show Broken".
[b]Ahh yeah this document was made before the new omni update and hasn't been edited in a long time xD Good catch :)
