ChimeraX Startup¶
The ChimeraX application runs on Microsoft Windows, macOS, and Linux.
By default, ChimeraX does an asynchronous network query of the ChimeraX Toolshed for available bundles at startup once a week. The interval can be changed in the Toolshed settings. The Toolshed query is implicitly turned off when certain command line arguments are given as noted below.
Command Line Arguments¶
When running ChimeraX from a terminal (a.k.a. a shell) it can be given
various options followed by data files.
The data files are specified with same syntax as the filename argument
of Models’ open()
.
Command line options can start with either a single dash or a double dash and may not be mixed.
Single Dash Commmand Line Options¶
All of the Python single dash command line options are recognized. The presence of any single dash argument turns off querying the Toolshed at startup. Most are ignored except for the following:
-c command
Only recognized if it is the first argument. Act like the Python interpreter and run the Python command with the rest of the arguments in
sys.argv
. Implies--nogui
and--silent
. This is done after ChimeraX has started up, so a ChimeraX session is available in the global variablesession
.-d
Turn on debugging.
-h
Show command line help.
-m module
Only recognized if it is the first argument. Act like the Python interpreter and run the module as the main module and the rest of the arguments are in
sys.argv
. Implies--nogui
and--silent
. This is done after ChimeraX has started up, so a ChimeraX session is available in the global variablesession
. The module name is__main__
instead of a sandbox name that is used for normalscripting
.-u
Force the stdout and stderr streams to be unbuffered.
-V
Prints the internal Python version and exits.
Double Dash Command Line Options¶
The follow command line arguments are recognized:
--cmd command
Run the ChimeraX command at startup after starting tools. Turns off querying the Toolshed at startup.
--color
Turn on colored text in nogui mode (default).
--nocolor
Turn off colored text in nogui mode.
--debug
Turn on debugging code. Accessing within ChimeraX with
session.debug
.--devel
Turn on development mode. Currently, just enables Python deprecation warnings.
--exit
Exit immediately after processing command line arguments. Turns off querying the Toolshed at startup.
--noexit
Do not exit after processing command line arguments (default). Turns off querying the Toolshed at startup (not default).
--lineprofile
Turn on line profiling. See Line Profiling for details. Turns off querying the Toolshed at startup.
--listioformats
Show all recognized file suffixes and if they can be opened or saved. Turns off querying the Toolshed at startup.
--nogui
Turn off the gui. Access with ChimeraX with
session.ui.is_gui
.--nostatus
Don’t output to status line.
--notools
Do not autostart any tools at startup.
--offscreen
Run without a gui but allow rendering images that can be saved to files, i.e., implies
--nogui
. This uses OSMesa for rendering which will not make use of a GPU, so rendering can be slow. But it can run on a server without a display.--safemode
Don’t run bundle custom initialization code nor load any tools.
--script python-script
Run Python script at startup. If they Python script has any specific arguments, they should be quoted along with the script name. Turns off querying the Toolshed at startup.
--silent
Don’t output startup splash text and otherwise refrain from being verbose.
--start_tool tool_name
Start the named tool during ChimeraX startup after the autostart tools.
--tools
Run ChimeraX tools at startup (default).
--notools
Don’t run ChimeraX tools at startup.
--toolshed URL
Set the URL to use for the toolshed. The special name preview is recognized for using a preview of the next revision of the toolshed (currently only available internally).
--uninstall
If needed, deregister any icons or mime types, then remove as much of the installation directory as possible. Intended for use by system App Store or package manager.
--usedefaults
Ignore user settings and use default settings. Not implemented yet.
--version
Print out current version. If given two times, then all of installed ChimeraX tools verions are listed. If given three times, then all of installed Python package versions are listed.
Run Custom Python Code at Start Up¶
To have ChimeraX run custom Python code each time you start it you can put Python files in directory
~/chimerax_start
Each Python file will be executed with the variable “session” added to the global namespace. For example, the following line put in ~/chimerax_start/starttools.py automatically starts the File History panel and Density Map toolbar.
session.tools.start_tools((‘File History’, ‘Density Map Toolbar’))
Python code can be used to register new commands, add mouse modes and file readers that you develop. In addition to executing Python files in the directory, the startup directory will be appended to the Python sys.path search path so Python modules in the subdirectory can be imported. Subdirectories in the startup directory that contain an __init__.py file will be imported and if they contain a function named “start” it will be called with session as an argument.
To use a directory other than ~/chimerax_start as the startup directory set the environment variable CHIMERAX_START to the desired directory in the shell where Chimera is started.
Initializing the Session¶
A Session
instance is passed as an
argument to many functions.
It is the way to access per-session data.
Leaf functions frequently are only given one attribute (or none at all).
session.debug
True if debugging.
session.logger
A
Log
instance to log errors to.session.app_dirs
A versioned
AppDirs
instance with directories to look for application and user files in.session.app_dirs_unversioned
An unversioned
AppDirs
instance with directories to look for application and user files in.session.app_data_dir
The location of “share” directory.
session.ui
A
Log
instance.session.toolshed
A
Toolshed
instance.session.tools
A
Tools
instance.session.tasks
A
Tasks
instance.
Other initial sessiona attributes are initialized in chimerax.core.session.common_startup()
.