dials.import

Introduction

This program is used to import image data files into a format that can be used within dials. The program looks at the metadata for each image along with the filenames to determine the relationship between sets of images. Once all the images have been analysed, a datablock object is written to file which specifies the relationship between files. For example if two sets of images which belong to two rotation scans have been given, two image sweeps will be saved. Images to be processed are specified as command line arguments. Sometimes, there is a maximum number of arguments that can be given on the command line and the number of files may exceed this. In this case image filenames can be input on stdin as shown in the examples below. Alternatively a template can be specified using the template= parameter where the consecutive digits representing the image numbers in the filenames are replaced with ‘#’ characters.

The geometry can be set manually by either specifying a datablock.json file containing the reference geometry, by setting the mosflm beam centre or by setting each variable to be overridden.

Examples:

dials.import /data/directory-containing-images/

dials.import image_*.cbf

dials.import image_1_*.cbf image_2_*.cbf

dials.import directory/with/images

dials.import template=image_1_####.cbf

dials.import directory=directory/with/images

find . -name "image_*.cbf" | dials.import

dials.import << EOF
image_1.cbf
image_2.cbf
EOF

Basic parameters

output {
  datablock = datablock.json
  log = 'dials.import.log'
  debug_log = 'dials.import.debug.log'
  compact = False
}
verbosity = 1
input {
  ignore_unhandled = False
  template = None
  directory = None
  reference_geometry = None
  allow_multiple_sweeps = False
  as_grid_scan = False
  grid_size = None
}
lookup {
  mask = None
  gain = None
  pedestal = None
  dx = None
  dy = None
}

Full parameter definitions

output {
  datablock = datablock.json
    .help = "The output JSON or pickle file"
    .type = str
  log = 'dials.import.log'
    .help = "The log filename"
    .type = str
  debug_log = 'dials.import.debug.log'
    .help = "The debug log filename"
    .type = str
  compact = False
    .help = "For JSON output use compact representation"
    .type = bool
}
verbosity = 1
  .help = "The verbosity level"
  .type = int(value_min=0)
input {
  ignore_unhandled = False
    .help = "Don't throw exception if some args are unhandled"
    .type = bool
  template = None
    .help = "The image sweep template"
    .type = str
    .multiple = True
  directory = None
    .help = "A directory with images"
    .type = str
    .multiple = True
  reference_geometry = None
    .help = "Experimental geometry from this datablock.json or "
            "experiments.json will override the geometry from the  image"
            "headers."
    .type = path
  allow_multiple_sweeps = False
    .help = "If False, raise an error if multiple sweeps are found"
    .type = bool
  as_grid_scan = False
    .help = "Import as grid scan"
    .type = bool
  grid_size = None
    .help = "If importing as a grid scan set the size"
    .type = ints(size=2)
}
format
  .help = "Options to pass to the Format class"
  .expert_level = 2
{
  dynamic_shadowing = auto
    .help = "Enable dynamic shadowing"
    .type = bool
  multi_panel = False
    .help = "Enable a multi-panel detector model. (Not supported by all"
            "detector formats)"
    .type = bool
}
geometry
  .help = "Allow overrides of experimental geometry"
  .expert_level = 2
{
  beam
    .short_caption = "Beam overrides"
    .expert_level = 1
  {
    wavelength = None
      .help = "Override the beam wavelength"
      .type = float
    direction = None
      .help = "Override the sample to source direction"
      .short_caption = "Sample to source direction"
      .type = floats(size=3)
  }
  detector
    .short_caption = "Detector overrides"
    .expert_level = 1
  {
    panel
      .multiple = True
    {
      id = 0
        .help = "The panel number"
        .short_caption = "Panel ID"
        .type = int
      name = None
        .help = "Override the panel name"
        .short_caption = "Panel name"
        .type = str
      type = None
        .help = "Override the panel type"
        .short_caption = "Panel type"
        .type = str
      gain = None
        .help = "The gain of the detector panel"
        .short_caption = "Gain value"
        .type = float(value_min=0)
      pixel_size = None
        .help = "Override the panel pixel size"
        .short_caption = "Panel pixel size"
        .type = floats(size=2)
      image_size = None
        .help = "Override the panel image size"
        .short_caption = "Panel image size"
        .type = ints(size=2)
      trusted_range = None
        .help = "Override the panel trusted range"
        .short_caption = "Panel trusted range"
        .type = floats(size=2)
      thickness = None
        .help = "Override the panel thickness"
        .short_caption = "Panel thickness"
        .type = float
      material = None
        .help = "Override the panel material"
        .short_caption = "Panel material"
        .type = str
      fast_axis = None
        .help = "Override the panel fast axis. Requires slow_axis and origin."
        .short_caption = "Panel fast axis direction"
        .type = floats(size=3)
      slow_axis = None
        .help = "Override the panel slow axis. Requires fast_axis and origin."
        .short_caption = "Panel slow axis direction"
        .type = floats(size=3)
      origin = None
        .help = "Override the panel origin. Requires fast_axis and slow_axis."
        .short_caption = "Panel origin vector"
        .type = floats(size=3)
      parallax_correction = None
        .help = "Enable parallax correction. By default in overwrite mode, the"
                "value of None does nothing."
        .short_caption = "Enable parallax correction"
        .type = bool
    }
    hierarchy {
      name = None
        .help = "Override the group name"
        .short_caption = "group name"
        .type = str
      fast_axis = None
        .help = "Override the panel fast axis. Requires slow_axis and origin."
        .short_caption = "Panel fast axis direction"
        .type = floats(size=3)
      slow_axis = None
        .help = "Override the panel slow axis. Requires fast_axis and origin."
        .short_caption = "Panel slow axis direction"
        .type = floats(size=3)
      origin = None
        .help = "Override the panel origin. Requires fast_axis and slow_axis."
        .short_caption = "Panel origin vector"
        .type = floats(size=3)
      group
        .multiple = True
      {
        id = None
          .help = "The group identifier specifying the place in the hierarchy"
          .short_caption = "Group ID"
          .type = ints
        name = None
          .help = "Override the group name"
          .short_caption = "Group name"
          .type = str
        fast_axis = None
          .help = "Override the group fast axis. Requires slow_axis and"
                  "origin."
          .short_caption = "Group fast axis direction"
          .type = floats(size=3)
        slow_axis = None
          .help = "Override the group slow axis. Requires fast_axis and"
                  "origin."
          .short_caption = "Group slow axis direction"
          .type = floats(size=3)
        origin = None
          .help = "Override the group origin. Requires fast_axis and"
                  "slow_axis."
          .short_caption = "Group origin vector"
          .type = floats(size=3)
        panel = None
          .help = "The panel id"
          .short_caption = "Panel ID"
          .type = int
          .multiple = True
      }
    }
    mosflm_beam_centre = None
      .help = "Override the beam centre from the image headers, following  the"
              "mosflm convention."
      .short_caption = "Beam centre coordinates (mm, mm) using the Mosflm"
                       "convention"
      .type = floats(size=2)
    distance = None
      .help = "The detector distance (used when mosflm_beam_centre is set)"
      .short_caption = "Detector distance"
      .type = float
    slow_fast_beam_centre = None
      .help = "Override the beam centre from the image headers, following  the"
              "slow/fast pixel convention used by dials.image_viewer. The"
              "first two values are the slow and fast pixel coordinate. If the"
              "third is supplied it specifies a panel number."
      .short_caption = "Beam centre coordinates (px slow, px fast, [panel id])"
      .type = ints(size_min=2, size_max=3)
  }
  goniometer
    .short_caption = "Goniometer overrides"
    .expert_level = 1
  {
    axes = None
      .help = "Override the goniometer axes. Axes must be provided in the"
              "order crystal-to-goniometer, i.e. for a Kappa goniometer"
              "phi,kappa,omega"
      .short_caption = "Goniometer axes"
      .type = floats
    angles = None
      .help = "Override the goniometer angles. Axes must be provided in the"
              "order crystal-to-goniometer, i.e. for a Kappa goniometer"
              "phi,kappa,omega"
      .short_caption = "Goniometer angles"
      .type = floats
    names = None
      .help = "The multi axis goniometer axis names"
      .short_caption = "The axis names"
      .type = str
    scan_axis = None
      .help = "The scan axis"
      .short_caption = "The scan axis"
      .type = int
    fixed_rotation = None
      .help = "Override the fixed rotation matrix"
      .short_caption = "Fixed rotation matrix"
      .type = floats(size=9)
    setting_rotation = None
      .help = "Override the setting rotation matrix"
      .short_caption = "Setting rotation matrix"
      .type = floats(size=9)
    invert_rotation_axis = False
      .help = "Invert the rotation axis"
      .short_caption = "Invert rotation axis"
      .type = bool
  }
  scan
    .short_caption = "Scan overrides"
    .expert_level = 1
  {
    image_range = None
      .help = "Override the image range"
      .short_caption = "Image range"
      .type = ints(size=2)
    extrapolate_scan = False
      .help = "When overriding the image range, extrapolate exposure and epoch"
              "information from existing images"
      .short_caption = "Extrapolate scan"
      .type = bool
    oscillation = None
      .help = "Override the image oscillation"
      .short_caption = Oscillation
      .type = floats(size=2)
    batch_offset = None
      .help = "Override the batch offset"
      .short_caption = "Batch offset"
      .type = int(value_min=0)
  }
  convert_stills_to_sweeps = False
    .help = "When overriding the scan, convert stills into sweeps"
    .short_caption = "Convert stills into sweeps"
    .type = bool
  convert_sweeps_to_stills = False
    .help = "When overriding the scan, convert sweeps into stills"
    .short_caption = "Convert sweeps into stills"
    .type = bool
}
lookup {
  mask = None
    .help = "Apply a mask to the imported data"
    .type = str
  gain = None
    .help = "Apply a gain to the imported data"
    .type = str
  pedestal = None
    .help = "Apply a pedestal to the imported data"
    .type = str
  dx = None
    .help = "Apply an x geometry offset If both dx and dy are set then"
            "OffsetParallaxCorrectedPxMmStrategy will be used"
    .type = str
  dy = None
    .help = "Apply an y geometry offset If both dx and dy are set then"
            "OffsetParallaxCorrectedPxMmStrategy will be used"
    .type = str
}