Source

General properties

The following properties can be specified in the source section of the scenario file.

The model name and the manufacturer, if an existing X-ray source is modelled:

"model":        "XS-1",
"manufacturer": "X-ray Tube Company",

The tube acceleration voltage and the target current:

"voltage": {"value": 130, "unit": "kV"},
"current": {"value": 143, "unit": "uA"}

Target

"target": {
  "material_id": "W",
  "type": "reflection",
  "thickness": null,
  "angle": {
    "incidence": {"value": 45, "unit": "deg"},
    "emission":  {"value": 45, "unit": "deg"}
  }
}

The target material is defined by providing a "material_id" that refers to a material declaration in the materials section of the file.

The "type" can be either a transmission target or a reflection target:

"type": "transmission",
"type": "reflection"

For a transmission target, its thickness must be specified:

"thickness": {"value": 3.0, "unit": "um"}

For a reflection target, this parameter should be set to null.

The angles of electron incidence and main X-ray emission can be defined and refer to the angles between the target surface and electron beam or main photon emission direction, respectively.

Spot intensity profile

"spot": {
  "size": {
    "u": {"value": 100.0, "unit": "um"},
    "v": {"value": 100.0, "unit": "um"},
    "w": {"value":   0.0, "unit": "um"}
  },
  "sigma": {
    "u": {"value":  50.0, "unit": "um"},
    "v": {"value":  50.0, "unit": "um"},
    "w": {"value":   0.0, "unit": "um"}
  },
  "intensity_map": {
    "file": {"value": "spot_profile.raw", "drifts": null},
    "type": "float32",
    "dim_x": 301,
    "dim_y": 301,
    "dim_z": null,
    "endian": "little",
    "headersize": 0
  }
}

The spot intensity profile is specified in the source’s "spot" section. At first, the "size" of the virtual spot rectangle or volume is defined along the three axes of the source coordinate system. If only a two-dimensional spot profile is modelled, the size along the source’s normal axis should be set to 0.

If the spot size is set to null, the simulation software is free to choose a size that matches the required (Gaussian) shape.

"size": null

The shape of the spot can be defined in the following three ways.

Simple Gaussian profiles

A simple Gaussian profile can be modelled by specifying the spatial sigmas $\sigma$ for each dimension:

$I(\vec{r})=I_0\cdot\exp(-|\vec{r}|^2/2\sigma^2)$

"sigma": {
  "u": {"value":  50.0, "unit": "um"},
  "v": {"value":  50.0, "unit": "um"},
  "w": {"value":   0.0, "unit": "um"}
},

2D images

For a more detailed approach, the intensity profile can also be provided from an external image file. In this case, the $\vec{u}$ vector of the source coordinate system points from left to right in the image, and the $\vec{v}$ vector points from top to bottom, in analogy to the detector geometry. The image shall be resized to match the given "size" of the spot rectangle, without necessarily retaining the original aspect ratio of the image. The picture is recommended to be a 32 bit float gray-scale image and the pixel values in the interval [0, 1], with 0 meaning no intensity, and 1 meaning full intensity. However, a simulation software must also support gray-scale integer file formats and be able to re-normalize the provided gray values accordingly.

If a valid spot intensity image is provided, this method takes precedence over the previously described specification of Gaussian sigmas.

Further details about referring to two-dimensional data files (RAW or TIFF) are given in the section about General structures.

3D volumes

To describe a three-dimensional spot profile, a RAW file can be provided. It is recommended to be a 32 bit float volume with values between 0 and 1, and should otherwise be re-normalized by the simulation software. The lowest value means no intensity, the highest value means maximum intensity. If specified, this method takes precedence over the first two described methods.

The $x$ direction of the given volume points along the $\vec{u}$ vector of the source coordinate system, $y$ points in direction $\vec{v}$ , and $z$ in direction $\vec{w}$ . The volume shall be resized to match the "size" of the spot volume, without necessarily retaining the original aspect ratio of the volume file.

Further details about referring to three-dimensional data files (RAW volumes) are given in the section about General structures.

Spectrum

If the spectrum is to be calculated by the simulation software, the following three parameters decide whether only a monochromatic energy scenario is described or a complete spectrum. If a valid spectrum file is provided, it takes precendence over the monochromatic mode. If no spectrum file is provided, a simulation software is free to generate its own spectrum from the given tube parameters.

"spectrum": {
  "monochromatic": false,
  "file": {"value": "tube_spectrum_130kV.tsv", "drifts": null}
}

The spectrum from the provided file is assumed to be already filtered by the tube’s window material, but not yet by any of the filters in front of the tube (as specified under Tube window and filters). The CSV or TSV spectrum file should contain the columns listed in Tab. 5, separated by a comma or tab character.

Tab. 5 Table structure for X-ray spectrum files.
Column	Property
1	Photon energy in keV
2	Number of photons in 1 / (s ⋅ sr ⋅ mA)
3	Uncertainty in the number of photons (optional)

The energy values correspond to the centre of the histogram bins. The interpolation between the bin values shall not be specified here and is left to the simulation software. If a valid spectrum file is specified and the "file" parameter is not set to null, this has precedence over the spectrum calculated by the simulation software or the monochromatic mode.

Tube window and filters

The "window" material(s) and the additional "filters" in front of the tube are specified in two separate JSON arrays. For both, an arbitrary number of materials and thicknesses can be specified. If a source spectrum is provided in a file, the spectrum is assumed to be already filtered by all "window" materials but not yet by any "filters".

The "material_id" refers to the material definition in the "materials" section of the file. Also, a window and filter "thickness" must be provided.

"window": [
  {
    "material_id": "Al",
    "thickness": {"value": 4.0, "unit": "mm"}
  }
],
"filters": [
  {
    "material_id": "Brass",
    "thickness": {"value": 0.2, "unit": "mm"}
  },
  {
    "material_id": "Cu",
    "thickness": {"value": 0.17, "unit": "mm"}
  }
]