LSDetector

class cbclib.LSDetector(data, frames, num_threads, parent, lsd_obj={'ang_th': 45.0, 'density_th': 0.5, 'log_eps': 0.0, 'scale': 0.8999999761581421, 'sigma_scale': 0.8999999761581421, 'quant': 0.019999999552965164}, streaks=<factory>, patterns=None)

A streak detector class. A class wrapper for streak detection based on Line Segment Detector [LSD] algorithm. Provides an interface to generate an indexing tabular data.

Parameters

• data (ndarray) – Background corrected detector data.

• frames (ndarray) – Frame indices of the detector images.

• num_threads (int) – Number of threads used in the calculations.

• parent (ReferenceType[CrystData]) – A reference to the parent cbclib.CrystData container.

• lsd_obj (LSD) – a Line Segment Detector object.

• streaks (Dict[int, Streaks]) – A dictionary of detected cbclib.Streaks streaks.

• patterns (Optional[ndarray]) – Normalized diffraction patterns.

contents()

Return a list of the attributes stored in the container that are initialised.

Return type

List[str]

Returns

List of the attributes stored in the container.

detect(cutoff, filter_threshold=0.0, group_threshold=1.0, dilation=0.0, profile='linear')

Perform the streak detection. The streak detection comprises three steps: an initial LSD detection of lines, a grouping of the detected lines and merging, if the normalized cross-correlation value if higher than the group_threshold, discarding the lines with a 0-order image moment lower than filter_threshold.

Parameters

• cutoff (float) – Distance cut-off value for lines grouping in pixels.

• filter_threshold (float) – Filtering threshold. A line is discarded if the 0-order image moment is lower than filter_threshold.

• group_threshold (float) – Grouping threshold. The lines are merged if the cross-correlation value of a pair of lines is higher than group_threshold.

• dilation (float) – Line mask dilation value in pixels.

• profile (str) –

  Line width profiles. The following keyword values are allowed:

  • tophat : Top-hat (rectangular) function profile.

  • linear : Linear (triangular) function profile.

  • quad : Quadratic (parabola) function profile.

  • gauss : Gaussian function profile.

Raises

ValueError – If there is no patterns inside the container.

Return type

LSDetectorFull

Returns

A new LSDetector container with streaks updated.

draw(max_val=1, dilation=0.0, profile='tophat')

Draw a pattern mask by using the detected streaks streaks.

Parameters

• max_val (int) – Maximal mask value

• dilation (float) – Line mask dilation in pixels.

• profile (str) –

  Line width profiles. The following keyword values are allowed:

  • tophat : Top-hat (rectangular) function profile.

  • linear : Linear (triangular) function profile.

  • quad : Quadratic (parabola) function profile.

  • gauss : Gaussian function profile.

Raises

ValueError – If there is no streaks inside the container.

Return type

ndarray

Returns

A pattern mask.

export_streaks()

Export streak_mask to the parent cbclib.CrystData data container.

Raises

• ValueError – If there is no streaks inside the container.

• ValueError – If there is no streak_mask inside the container.

export_table(dilation=0.0, concatenate=True)

Export normalised pattern into a pandas.DataFrame table.

Parameters

• dilation (float) – Line mask dilation in pixels.

• concatenate (bool) – Concatenate sets of patterns for each frame into a single table if True.

Raises

ValueError – If there is no streaks inside the container.

Return type

Union[DataFrame, List[DataFrame]]

Returns

List of pandas.DataFrame tables for each frame in frames if concatenate is False, a single pandas.DataFrame otherwise. Table contains the following information:

• frames : Frame index.

• x, y : Pixel coordinates.

• p : Normalised pattern values.

• rp : Reflection profiles.

• I_raw : Measured intensity.

• bgd : Background values.

generate_patterns(vmin, vmax, size=(1, 3, 3))

Generate a set of normalised diffraction patterns patterns based on taking a 2D median filter of background corrected detector images data and clipping the values to a (vmin, vmax) interval.

Parameters

• vmin (float) – Lower bound of the clipping range.

• vmax (float) – Upper bound of the clipping range.

• size (Union[Tuple[int, …], int]) – Size of the median filter footprint.

Raises

ValueError – If vmax is less than vmin.

Return type

~D

Returns

A new cbclib.LSDetector container with patterns updated.

get(attr, value=None)

Retrieve a dataset, return value if the attribute is not found.

Parameters

• attr (str) – Data attribute.

• value (Optional[Any]) – Data which is returned if the attribute is not found.

Return type

Any

Returns

Attribute’s data stored in the container, value if attr is not found.

items()

Return (key, value) pairs of the datasets stored in the container.

Return type

ItemsView

Returns

(key, value) pairs of the datasets stored in the container.

keys()

Return a list of the attributes available in the container.

Return type

List[str]

Returns

List of the attributes available in the container.

mask_frames(idxs)

Choose a subset of frames stored in the container and return a new detector object.

Parameters

idxs (Union[int, slice, ndarray, List[int], Tuple[int]]) – List of frame indices to choose.

Return type

~D

Returns

New detector object with the updated frames, data, streak_data, and streaks.

refine_streaks(dilation=0.0)

Refine detected diffraction streaks by fitting a Gaussian across the line.

Parameters

dilation (float) – Dilation radius in pixels used for the Gaussian fit.

Return type

~D

Returns

A new detector with the updated diffraction streaks.

replace(**kwargs)

Return a new container object with a set of attributes replaced.

Parameters

kwargs (Any) – A set of attributes and the values to to replace.

Return type

~D

Returns

A new container object with updated attributes.

to_dataframe(concatenate=True)

Export detected streak lines streaks to a pandas.DataFrame table.

Parameters

concatenate (bool) – Concatenate sets of streaks for each frame into a single table if True.

Raises

ValueError – If there is no streaks inside the container.

Return type

Union[DataFrame, List[DataFrame]]

Returns

List of pandas.DataFrame tables for each frame in frames if concatenate is False, a single pandas.DataFrame otherwise. Table contains the following information:

• frames : Frame index.

• streaks : Line index.

• x0, y0, x1, y1 : Line point coordinates in pixels.

• width : Line width.

• length : Line length.

update_lsd(scale=0.9, sigma_scale=0.9, log_eps=0.0, ang_th=45.0, density_th=0.5, quant=0.02)

Return a new LSDetector object with updated cbclib.bin.LSD detector.

Parameters

• scale (float) – When different from 1.0, LSD will scale the input image by ‘scale’ factor by Gaussian filtering, before detecting line segments.

• sigma_scale (float) – When scale is different from 1.0, the sigma of the Gaussian filter is sigma = sigma_scale / scale, if scale is less than 1.0, and sigma = sigma_scale otherwise.

• log_eps (float) – Detection threshold, accept if -log10(NFA) > log_eps. The larger the value, the more strict the detector is, and will result in less detections. The value -log10(NFA) is equivalent but more intuitive than NFA: * -1.0 gives an average of 10 false detections on noise. * 0.0 gives an average of 1 false detections on noise. * 1.0 gives an average of 0.1 false detections on nose. * 2.0 gives an average of 0.01 false detections on noise.

• ang_th (float) – Gradient angle tolerance in the region growing algorithm, in degrees.

• density_th (float) – Minimal proportion of ‘supporting’ points in a rectangle.

• quant (float) – Bound to the quantization error on the gradient norm. Example: if gray levels are quantized to integer steps, the gradient (computed by finite differences) error due to quantization will be bounded by 2.0, as the worst case is when the error are 1 and -1, that gives an error of 2.0.

Return type

~D

Returns

A new LSDetector with the updated lsd_obj.

update_patterns(dilations=(1.0, 3.0, 7.0))

Return a new detector object with updated normalised CBC patterns. The image is segmented into two region around each reflection to calculate the local background and local peak intensity. The estimated values are used to normalise each diffraction streak separately.

Parameters

dilations (Tuple[float, float, float]) –

A tuple of three dilations (d0, d1, d2) in pixels of the streak mask that is used to define the inner and outer streak zones:

• The inner zone is based on the mask dilated by d0.

• The outer zone is based on the difference between a mask dilated by d2 and by d1.

Return type

~D

Returns

A new detector object with updated patterns.

values()

Return the attributes’ data stored in the container.

Return type

ValuesView

Returns

List of data stored in the container.