-f filename.jsonor
-f filename.inp
filename may contain absolute or relative path. If the filename has a '.json' extension, this input file is in the JSON format. If the input file name ends with '.inp', it is in the legacy format. If the file name contains space, one must use quotation marks to quote the full file name. In Windows, the quotation must be double quote (""). In Linux or Mac, either single or double quotation mark works.
If this flag is followed by an inline JSON string, such as -f '{...}', the parameter is parsed as an "inline JSON input file".
-n N
where N can be either an integer, such as 100000 or a floating point number, such as 1e5. If N is a floating point number, it will be rounded to the largest integer below the current value. If this number is larger than 1e9, we suggest one to use the "-r" option followed by an integer larger than 1.
-r N
where N is a positive integer. When use this option, mcx runs 'total photon number/N' photons in a batch.
This option is useful when one does not have access to a dedicated GPU, i.e. the GPU is used for both display and computation. In such case, the mcx computation time is limited to only 5 to 10 seconds due to the graphics driver. One can use the -r option to make the execution time per batch under the time limit set by the driver.
Starting from version 0.7.9, MCX accepts a JSON-formatted input file in addition to the conventional tMCimg-like input format. JSON (JavaScript Object Notation) is a portable, human-readable and "fat-free" text format to represent complex and hierarchical data. Using the JSON format makes a input file self-explanatory, extensible and easy-to-interface with other applications (like MATLAB).
A sample JSON input file can be found under the examples/quicktest folder. The same file, qtest.json, is also shown below:
{ "Help": { "[en]": { "Domain::VolumeFile": "file full path to the volume description file, can be a binary or JSON file", "Domain::Dim": "dimension of the data array stored in the volume file", "Domain::OriginType": "similar to --srcfrom0, 1 if the origin is [0 0 0], 0 if it is [1.0,1.0,1.0]", "Domain::LengthUnit": "define the voxel length in mm, similar to --unitinmm", "Domain::Media": "the first medium is always assigned to voxels with a value of 0 or outside of the volume, the second row is for medium type 1, and so on. mua and mus must be in 1/mm unit", "Session::Photons": "if -n is not specified in the command line, this defines the total photon number", "Session::ID": "if -s is not specified in the command line, this defines the output file name stub", "Forward::T0": "the start time of the simulation, in seconds", "Forward::T1": "the end time of the simulation, in seconds", "Forward::Dt": "the width of each time window, in seconds", "Optode::Source::Pos": "the grid position of the source, can be non-integers, in grid unit", "Optode::Detector::Pos": "the grid position of a detector, can be non-integers, in grid unit", "Optode::Source::Dir": "the unitary directional vector of the photon at launch", "Optode::Source::Type": "source types, must be one of the following: pencil,isotropic,cone,gaussian,planar,pattern,fourier,arcsine,disk,fourierx,fourierx2d", "Optode::Source::Param1": "source parameters, 4 floating-point numbers", "Optode::Source::Param2": "additional source parameters, 4 floating-point numbers" } }, "Domain": { "VolumeFile": "semi60x60x60.bin", "Dim": [60,60,60], "OriginType": 1, "LengthUnit": 1, "Media": [ {"mua": 0.00, "mus": 0.0, "g": 1.00, "n": 1.0}, {"mua": 0.005,"mus": 1.0, "g": 0.01, "n": 1.0} ] }, "Session": { "Photons": 1000000, "RNGSeed": 29012392, "ID": "qtest" }, "Forward": { "T0": 0.0e+00, "T1": 5.0e-09, "Dt": 5.0e-09 }, "Optode": { "Source": { "Pos": [29.0, 29.0, 0.0], "Dir": [0.0, 0.0, 1.0], "Type": "pencil", "Param1": [0.0, 0.0, 0.0, 0.0], "Param2": [0.0, 0.0, 0.0, 0.0] }, "Detector": [ { "Pos": [29.0, 19.0, 0.0], "R": 1.0 }, { "Pos": [29.0, 39.0, 0.0], "R": 1.0 }, { "Pos": [19.0, 29.0, 0.0], "R": 1.0 }, { "Pos": [39.0, 29.0, 0.0], "R": 1.0 } ] } }
A JSON input file requiers several root objects, namely "Domain", "Session", "Forward" and "Optode". Other root sections, like "Help", will be ignored. Each object is a data structure providing information indicated by its name. Each object can contain various sub-fields. The orders of the fields in the same level are flexible. For each field, you can always find the equivalent fields in the *.inp input files. For example, The "VolumeFile" field under the "Domain" object is the same as Line#6 in qtest.inp; the "RNGSeed" under "Session" is the same as Line#2; the "Optode.Source.Pos" is the same as the triplet in Line#3; the "Forward.T0" is the same as the first number in Line#5, etc.
An MCX JSON input file must be a valid JSON text file. You can validate your input file by running a JSON validator, for example http://jsonlint.com/ You should always use "" to quote a "name" and separate parallel items by ",".
MCX accepts an alternative form of JSON input, but using it is not recommended. In the alternative format, you can use
"rootobj_name.field_name": valueto represent any parameter directly in the root level. For example
{ "Domain.VolumeFile": "semi60x60x60.json", "Session.Photons": 10000000, ... }
You can even mix the alternative format with the standard format. If any input parameter has values in both formats in a single input file, the standard-formatted value has higher priority.
To invoke the JSON-formatted input file in your simulations, you can use the "-f" command line option with MCX, just like using an .inp file. For example:
mcx -A -n 20 -f onecube.json -s onecubejson
The input file must have a ".json" suffix in order for MCX to recognize. If the input information is set in both command line, and input file, the command line value has higher priority (this is the same for .inp input files). For example, when using "-n 20", the value set in "Session"/"Photons" is overwritten to 20; when using "-s onecubejson", the "Session"/"ID" value is modified. If your JSON input file is invalid, MCX will quit and point out where the format is incorrect.
Historically, MCX supports an extended version of the input file format used by tMCimg. The difference is that MCX allows comments in the input file. A typical MCX input file looks like this:
1000000 # total photon, use -n to overwrite in the command line 29012392 # RNG seed, negative to generate 30.0 30.0 0.0 1 # source position (in grid unit), the last num (optional) sets srcfrom0 (-z) 0 0 1 # initial directional vector 0.e+00 1.e-09 1.e-10 # time-gates(s): start, end, step semi60x60x60.bin # volume ('unsigned char' binary format) 1 60 1 60 # x voxel size in mm (isotropic only), dim, start/end indices 1 60 1 60 # y voxel size, must be same as x, dim, start/end indices 1 60 1 60 # y voxel size, must be same as x, dim, start/end indices 1 # num of media 1.010101 0.01 0.005 1.37 # scat. mus (1/mm), g, mua (1/mm), n 4 1.0 # detector number and default radius (in grid unit) 30.0 20.0 0.0 2.0 # detector 1 position (real numbers in grid unit) and individual radius (optional) 30.0 40.0 0.0 # ..., if individual radius is ignored, MCX will use the default radius 20.0 30.0 0.0 # 40.0 30.0 0.0 # pencil # source type (optional) 0 0 0 0 # parameters (4 floats) for the selected source 0 0 0 0 # additional source parameters
Note that the scattering coefficient mus=musp/(1-g).
Starting from v0.7.9, MCX can also use a shape description file in the place of the volume file. Using a shape-description file can save you from making a binary .bin volume. A shape file uses more descriptive syntax and can be easily understood and shared with others.
Samples on how to use the shape files are included under the example/shapetest folder.
The sample shape file, shapes.json, is shown below:
{ "MCX_Shape_Command_Help":{ "Shapes::Common Rules": "Shapes is an array object. The Tag field sets the voxel value for each region; if Tag is missing, use 0. Tag must be smaller than the maximum media number in the input file.Most parameters are in floating-point (FP). If a parameter is a coordinate, it assumes the origin is defined at the lowest corner of the first voxel, unless user overwrite with an Origin object. The default origin of all shapes is initialized by user's --srcfrom0 setting: if srcfrom0=1, the lowest corner of the 1st voxel is [0,0,0]; otherwise, it is [1,1,1]", "Shapes::Name": "Just for documentation purposes, not parsed in MCX", "Shapes::Origin": "A floating-point (FP) triplet, set coordinate origin for the subsequent objects", "Shapes::Grid": "Recreate the background grid with the given dimension (Size) and fill-value (Tag)", "Shapes::Sphere": "A 3D sphere, centered at C0 with radius R, both have FP values", "Shapes::Box": "A 3D box, with lower corner O and edge length Size, both have FP values", "Shapes::SubGrid": "A sub-section of the grid, integer O- and Size-triplet, inclusive of both ends", "Shapes::XLayers/YLayers/ZLayers": "Layered structures, defined by an array of integer triples: [start,end,tag]. Ends are inclusive in MATLAB array indices. XLayers are perpendicular to x-axis, and so on", "Shapes::XSlabs/YSlabs/ZSlabs": "Slab structures, consisted of a list of FP pairs [start,end] both ends are inclusive in MATLAB array indices, all XSlabs are perpendicular to x-axis, and so on", "Shapes::Cylinder": "A finite cylinder, defined by the two ends, C0 and C1, along the axis and a radius R", "Shapes::UpperSpace": "A semi-space defined by inequality A*x+B*y+C*z>D, Coef is required, but not Equ" }, "Shapes": [ {"Name": "Test"}, {"Origin": [0,0,0]}, {"Grid": {"Tag":1, "Size":[40,60,50]}}, {"Sphere": {"Tag":2, "O":[30,30,30],"R":20}}, {"Box": {"Tag":0, "O":[10,10,10],"Size":[10,10,10]}}, {"Subgrid": {"Tag":1, "O":[13,13,13],"Size":[5,5,5]}}, {"UpperSpace":{"Tag":3,"Coef":[1,-1,0,0],"Equ":"A*x+B*y+C*z>D"}}, {"XSlabs": {"Tag":4, "Bound":[[5,15],[35,40]]}}, {"Cylinder": {"Tag":2, "C0": [0.0,0.0,0.0], "C1": [15.0,8.0,10.0], "R": 4.0}}, {"ZLayers": [[1,10,1],[11,30,2],[31,50,3]]} ] }
A shape file must contain a "Shapes" object in the root level. Other root-level fields are ignored. The "Shapes" object is a JSON array, with each element representing a 3D object or setting. The object-class commands include "Grid", "Sphere", "Box" etc. Each of these object include a number of sub-fields to specify the parameters of the object. For example, the "Sphere" object has 3 subfields, "O", "R" and "Tag". Field "O" has a value of 1x3 array, representing the center of the sphere; "R" is a scalar for the radius; "Tag" is the voxel values. The most useful command is "[XYZ]Layers". It contains a series of integer triplets, specifying the starting index, ending index and voxel value of a layered structure. If multiple objects are included, the subsequent objects always overwrite the overlapping regions covered by the previous objects.
There are a few ways for you to use shape description records in your MCX simulations. You can save it to a JSON shape file, and put the file name in Line#6 of yoru .inp file, or set as the value for Domain.VolumeFile field in a .json input file. In these cases, a shape file must have a suffix of .json.
You can also merge the Shapes section with a .json input file by simply appending the Shapes section to the root-level object. You can find an example, jsonshape_allinone.json, under examples/shapetest. In this case, you no longer need to define the "VolumeFile" field in the input.
Another way to use Shapes is to specify it using the -P (or --shapes) command line flag. For example:
mcx -f input.json -P '{"Shapes":[{"ZLayers":[[1,10,1],[11,30,2],[31,60,3]]}]}'
This will first initialize a volume based on the settings in the input .json file, and then rasterize new objects to the domain and overwrite regions that are overlapping.
For both JSON-formatted input and shape files, you can use the JSONlab toolbox [4] to load and process in MATLAB.