Cartool can be called directly from the command-line, f.ex. from Windows batch files, Matlab or Python scripts, and therefor be used as a library for all sorts of processing pipe-lines. To finer control its behavior, you can pass it general options, described here, or sub-commands, described for each related toolbox.
This will not be a full tutorial on the CLI11 Command-Line syntax, but just a guidelines to help you get the job done:
To get the latest up-to-date list of sub-commands and options, simply call:
cartool64.exe --help or cartool64.exe <subcommand> --help or cartool64.exe --help <subcommand>
The current Cartool version can be retrieved with:
cartool64.exe --version
You can control the Cartool main window state, size and position with:
cartool64.exe --mainwindow={minimized,maximized,normal} [maximized]
--mainwindowsize=width,height
--mainwindowpos=x,y
You can skip the splash-screen with:
cartool64.exe --nosplash
And you can even select which monitor to open Cartool to:
cartool64.exe --monitor=<number>
Note that the monitor index might differ from what the Control Panel shows you, though. This is a Windows thing, sorry about that...
Opening Cartool on the top left part of the screen, resized for HD:
cartool64.exe --mainwindowpos=0,0 --mainwindowsize=1920,1080
Fast opening Cartool full screen on a second monitor:
cartool64.exe --mainwindow=maximized --monitor=2 --nosplash
You can control every new opened file child window state, size and position by using any of these options before a given file (note the "--" before the files):
cartool64.exe --childwindow={minimized,maximized,normal} [normal]
--childwindowsize=width,height
--childwindowpos=x,y
-- <files>
Each of these parameters could be repeated for each file with different values. In case some parameters are missing, the last valid ones will be used.
Also note that, for the moment, you can not specify any parameter for the nth file without specifying the parameters of all previous files!
Single file opened maximized:
cartool64.exe --childwindow=maximized -- <file1>
First file opened normally, next one opened minimized:
cartool64.exe --childwindow=normal -- <file1> --childwindow=minimized -- <file2> or cartool64.exe --childwindow=normal minimized -- <file1> <file2>
First file opened normally, 2 successive files opened minimized:
cartool64.exe --childwindow=normal -- <file1> --childwindow=minimized -- <file2> <file3>
First file opened normally, 2 successive files opened minimized, last one opened maximized:
cartool64.exe --childwindow=normal minimized minimized maximized -- <file1> <file2> <file3> <file4>
Single file opened normally, with overridden size and position:
cartool64.exe --childwindowsize=500,250 --childwindowpos=0,0 -- <file1>
Single file resized and repositionned, then minimized:
cartool64.exe --childwindow=minimized --childwindowsize=500,250 --childwindowpos=0,0 -- <file1>
Two files opened normally, with overridden sizes and positions:
cartool64.exe --childwindowsize=500,250 200,800 --childwindowpos=0,0 500,250 -- <file1> <file2>
When providing files to the command-line, you can use either absolute or relative paths, each way coming with its own pros and cons.
Providing absolute paths has the advantage of being unambigous and therefor safe. It also allows for mixing data from different directories. Disadvantages are they are longer to specify, and needs updating if said files got moved around...
Here is an example where the electrodes coordinates file comes from one directory, and the EEG data from another one:
cartool64.exe reprocesstracks --xyzfile=D:\Data\Electrodes\Biosemi.128.xyz --ext=eeg -- D:\Data\EEG\Subject1.nsr
Another example that uses 3 different input directories:
cartool64d.exe computingris --preset=ErpGrandAverages --isfile=D:\Data\Inverses\MNI152.NlinAsym20.4Shell.EGI204.6mm.2025.eLORETA.is --xyzfile=D:\Data\Electrodes\MNI152.NlinAsym20.204.2023.xyz --spatialfilter --type=norm --reg=4 --savingsubjects -- "D:\Data\EEG\Face.Avg RISE1.V1.Recut.sef"
Absolute paths, although safe, can be tedious to use as they tend to be very long and verbosey. They also break any script if the files move location. The alternative is to use relative paths, but they need to be resolved as absolute path at some point:
Example of the default behavior, without the --input-dir option:
cartool64.exe reprocesstracks --xyzfile=Biosemi.128.xyz --ext=eeg -- Subject1.nsr
will be resolve using the current Cartool execution directory, usually C:\Program Files\Cartool:
cartool64.exe reprocesstracks --xyzfile=C:\Program Files\Cartool\Biosemi.128.xyz --ext=eeg -- C:\Program Files\Cartool\Subject1.nsr
Example with the --input-dir option, if both electrodes and EEG data is located under D:\Data:
cartool64.exe reprocesstracks --input-dir=D:\Data --xyzfile=Biosemi.128.xyz --ext=eeg -- Subject1.nsr
will be resolve as:
cartool64.exe reprocesstracks --xyzfile=D:\Data\Biosemi.128.xyz --ext=eeg -- D:\Data\Subject1.nsr
Or, if data is located under sub-directories D:\Data\Electrodes and D:\Data\EEG respectively:
cartool64.exe reprocesstracks --input-dir=D:\Data --xyzfile=Electrodes\Biosemi.128.xyz --ext=eeg -- EEG\Subject1.nsr
will be resolve as:
cartool64.exe reprocesstracks --xyzfile=D:\Data\Electrodes\Biosemi.128.xyz --ext=eeg -- D:\Data\EEG\Subject1.nsr
Finally, one can also mix relative and absolute paths, for example here using an absolute path for the electrodes coordinates, and relative paths for the EEGs:
cartool64.exe reprocesstracks --xyzfile=D:\Data\Electrodes\Biosemi.128.xyz --ext=eeg --input-dir=D:\Data\EEG -- Subject1.nsr Subject2.nsr Subject3.nsr
Use this option to convert relative paths to absolute ones, by prefixing them with the specified (absolute) directory path. For example, if both electrodes and EEG data is located under D:\Data, you could call:
cartool64.exe reprocesstracks --input-dir=D:\Data --xyzfile=Biosemi.128.xyz --ext=eeg -- Subject1.nsr
and all relative paths will be resolved as the equivalent parameters:
cartool64.exe reprocesstracks --xyzfile=D:\Data\Biosemi.128.xyz --ext=eeg -- D:\Data\Subject1.nsr
This option controls where all the output files and results will be written. For example, if the input data is located under D:\Data, but output data has to be in E:\Data\Results, you could call:
cartool64.exe reprocesstracks --input-dir=D:\Data --output-dir=E:\Data\Results --xyzfile=Biosemi.128.xyz --ext=eeg -- Subject1.nsr
Currently opens up a console showing a recap of your input parameters, à la verbose file. It also shows some real-time progress as each file is being processed.
Option is exclusive with --quiet.
This option forces a totally silent execution, with no messages, pop-ups, console nor any input requests of any sort.
Option is exclusive with --verbose.
This option forces any previously existing output files to be silently overwritten. This means that even if you repeat the same processing multiple times, you will overwrite the old results each time, and end up with only the latest results. Although kind of radical, this is very handy for results retrieval within a script, as you can always predict the output file names, which is not the case with the --no-overwrite option (see below).
Option is exclusive with --no-overwrite, obviously.
This option will prevent any deletion or overwriting of any existing file(s). This is a safety flag, useful if you want to keep previous results when running the same processing again and again. Note that this is the default behavior when processing data from Cartool's dialogs.
If an output file already exists, say "D:\Data\MyResults.eeg", then Cartool will use the variation "D:\Data\MyResults_1.eeg" instead. If the latter also exists, it will actually iterate until it finds the one variation that does not exist yet, f.ex. "D:\Data\MyResults_2.eeg" here.
Option is exclusive with --overwrite, obviously.
Sub-commands allow to run a specific toolbox or processing of Cartool. Each sub-command has its own set of options, which are therefor not available to the other sub-commands. Sub-commands can also make use of (most of) the general options above, though.
Registering Cartool to Windows allows for double-click file opening, icons and files associations etc... These associations are silently set for you by the Cartool installer, once and for all. But if anything gets corrupted, like erroneous icons and files associations, it is possible to invoke this registration manually. Still not an everyday manoeuvre, though...
Registration is a sub-command, with only one of these exclusive options :
cartool64.exe register --{yes,no,reset,help}
Also note that upon execution, Cartool will exit straight away. It might be necessary to reboot your machine if things get confusing for Windows, though most of the time, you need not.