The object_tools module.

The main functions are:

Detailed Module Contents

The entire module is documented below.

object_tools module.

@author: Peter Clark

cohobj.object_tools.label_3D_cyclic(mask, fast_overlap=False)

Label 3D objects taking account of cyclic boundary in x and y.

Uses ndimage(label) as primary engine.

Parameters:

mask (xarray.DataArray bool) – 3D logical array with object mask (i.e. objects are contiguous True).

Returns:

labels : -1 denotes unlabelled.

Return type:

xr.DataArray

cohobj.object_tools.remap_labels(labels: DataArray, label_index: list[int]) → DataArray

Change labels to sequential integers.

Parameters:

  • labels (xr.DataArray) – Array of integer labels.

  • label_index (list[int]) – Inverse mapping - label_index[i] contains existing label, changed to i.

Returns:

labels : Array of integer labels.

Return type:

xr.DataArray

cohobj.object_tools.get_object_labels(mask: DataArray) → DataArray

Convert 3D logical mask to object labels corresponding to mask positions.

Parameters:

mask (xr.DataArray) – Evaluates True at required positions.

Returns:

Data variables “object_labels”, counting from 0. Coordinates “pos_number” and any others (e.g. “time”) in mask.

Return type:

xr.DataArray (int32)

cohobj.object_tools.unsplit_objects(ds_traj, Lx=None, Ly=None) → Dataset

Unsplit a set of objects at a set of times using unsplit_object on each.

Parameters:

  • ds_traj (xr.Dataset) – Trajectory points “x”, “y”, and “z” and “object_label”.

  • Lx (Domain size in x and y directions.) –

  • Ly (Domain size in x and y directions.) –

Returns:

Trajectory array with modified positions.

Return type:

xr.Dataset

cohobj.object_tools.get_bounding_boxes(ds_traj, use_mask=False)

Find x,y,z min and max for objects in ds_traj.

Parameters:

  • ds_traj (xarray.Dataset) – Trajectory points “x”, “y”, “z” with additional non-dim coord “object_label” to groupby objects. and optional “object_mask” boolean data_var.

  • use_mask (bool, optional) – If true, only use points masked True by “object_mask”. The default is False.

Returns:

Dataset with {x/y/z}_{min/max/mean} for objects.

Return type:

xarray.Dataset

cohobj.object_tools.box_bounds(b: Dataset) → Dataset

Select object box boundaries from Dataset.

Parameters:

b (xr.Dataset) – Dataset containing box boundaries.

Returns:

Dataset containing just box boundaries.

Return type:

xr.Dataset

cohobj.object_tools.box_xyz(b)

Convert object bounds to plottable x,y,z for a box.

Parameters:

b (xarray.Dataset) – Contains {x/y/z}_{min/max}

Returns:

  • x (numpy array) – x values for box.

  • y (numpy array) – y values for box.

  • z (numpy array) – z values for box.

cohobj.object_tools.box_overlap_with_wrap(b_test, b_set, nx, ny)

Compute whether rectangular boxes intersect.

Parameters:

  • b_test (box for testing xarray.DataArray) –

  • b_set (set of boxes xarray.DataArray) –

  • nx (number of points in x grid.) –

  • ny (number of points in y grid.) –

Returns:

  • set – overlapping box ids

  • @author (Peter Clark)

cohobj.object_tools.refine_object_overlap_fast(tr1, tr2, nx, ny)

Estimate degree of overlap between two trajectory objects.

Parameters:

  • tr1 (np.array) – Trajectory data. [0:3,…] = [x, y, z] in grid points.

  • tr2 (np.array) – Trajectory data. [0:3,…] = [x, y, z] in grid points.

Returns:

Fractional overlap.

Return type:

float

cohobj.object_tools.refine_object_overlap(tr1, tr2)

Estimate degree of overlap between two trajectory objects.

Parameters:

  • tr1 (xarray.Dataset) – Trajectory Dataset.

  • tr2 (xarray.Dataset) – Trajectory Dataset.

Returns:

Fractional overlap.

Return type:

float

cohobj.object_tools.tr_objects_to_numpy(tr: Dataset, to_gridpoint: bool = False) → dict

Convert trajectory data from xarray.Datset to dictionary.

Parameters:

  • tr (xr.Dataset) – Contains ‘x’, ‘y’, ‘z’ and ‘object_mask’ variables, ‘time’ coordinate, ‘ref_time’ and ‘object_label’ non-dimensional coordinates.

  • to_gridpoint (bool, optional) – Convert physical units to grid points by dividing x by dx etc.. The default is False.

Returns:

  • ‘xyz’: position data as numpy array [3, time, trajectory_number],

  • ’mask’: in-object mask as numpy bool array [time, trajectory_number] ,

  • ’object_label’: Object numbers as numpy array [trajectory_number],

  • ’nobjects’ : int number of objects,

  • ’ref_time’ : reference time,

  • ’time’ : time as 1D numpy array,

  • ’attrs’: tr.attrs,

Return type:

dict

cohobj.object_tools.tr_data_at_time(traj: dict, req_time: float)

Select trajectory data at required time from dict format data.

Parameters:

  • traj (dict) – Trajectory data.

  • req_time (float) – Required time.

Returns:

Output data. Format as per input but time dimension absent.

Return type:

dict

cohobj.object_tools.tr_data_obj(traj: dict, iobj: int)

Select trajectory data from required object from dict format data.

Parameters:

  • traj (dict) – Trajectory data.

  • iobj (int) – Required object.

Returns:

Output data. Format as per input but just one object.

Return type:

dict