itkpocus package
Submodules
itkpocus.butterfly module
Preprocessing and device specific IO for the Butterfly iQ.
- itkpocus.butterfly.ffprobe_count_frames(filename)[source]
Get metadata by using ffprobe
Checks the output of ffprobe on the desired video file. MetaData is then parsed into a dictionary.
- Parameters
filename (string) – Path to the video file
- Returns
metaDict – Dictionary containing all header-based information about the passed-in source video.
- Return type
dict
- itkpocus.butterfly.load_and_preprocess_image(fp, version=None)[source]
Loads and preprocesses a Butterfly image.
- Parameters
fp (str) – filepath to image
version (optional) – Reserved for future use.
- Returns
img (itk.Image[itk.F,2]) – Floating point image with physical spacing set, origin is at upper-left of image, and intensities are between 0.0 and 1.0
meta (dict) – Meta data (includes spacing and crop)
- itkpocus.butterfly.load_and_preprocess_video(fp, version=None)[source]
Loads and preprocesses a Butterfly video.
- Parameters
fp (str) – filepath to video (e.g. .mp4)
version (optional) – Reserved for future use.
- Returns
img (itk.Image[itk.F,3]) – Floating point image with physical spacing set (3rd dimension is framerate), origin is at upper-left of image, and intensities are between 0.0 and 1.0
meta (dict) – Meta data (includes spacing and crop)
- itkpocus.butterfly.preprocess_image(npimg, version=None)[source]
- Parameters
npimg (ndarray) – RxCx3 (rgb), 0 to 255
version (None) – reserved for future use
- Returns
img (itk.Image[itk.F,2])
meta (dict)
- itkpocus.butterfly.preprocess_video(npvid, framerate=1, version=None)[source]
Preprocesses an ndarray representing a video (FRCRGB)
- Parameters
npvid (ndarray) – FxRxCx3 (rgb), 0 to 255
version (None) – reserved for future use
- Returns
img (itk.Image[itk.F,3])
meta (dict)
- itkpocus.butterfly.vread_workaround(fp, ffprobe_count_frames_dict=None)[source]
A workaround for Butterfly .mp4 files that don’t correctly set the number of frames. Forces vread to use the @nb_read_frames as the frame count.
- Parameters
fp (str) – File path to video file to read
ffprobe_count_frames_dict (dict, optional) – A dict from ffprobe containing the key ‘@nb_read_frames’. If not specified, ffprobe will be run on the file first.
- Returns
Video array in F,H,W,RGB format
- Return type
ndarray
itkpocus.clarius module
- itkpocus.clarius.load_and_preprocess_image(fp, version=None)[source]
Loads and preprocesses a Clarius image.
- Parameters
fp (str) – filepath to image
version (None) – Reserved for future use.
- Returns
img (itk.Image[itk.F,2]) – Floating point image with physical spacing set, origin is at upper-left of image, and intensities are between 0.0 and 1.0
meta (dict) – Meta data (includes spacing and crop)
- itkpocus.clarius.load_and_preprocess_video(fp, version=None)[source]
Loads and preprocesses a Clarius video.
- Parameters
fp (str) – filepath to video (e.g. .mp4)
version (optional) – Reserved for future use.
- Returns
img (itk.Image[itk.F,3]) – Floating point image with physical spacing set (3rd dimension is framerate), origin is at upper-left of image, and intensities are between 0.0 and 1.0
meta (dict) – Meta data (includes spacing and crop)
- itkpocus.clarius.preprocess_image(npimg, version=None)[source]
Calculate physical spacing of image from identified ruler within image and crops to B-mode only.
- Parameters
npimg (ndararay) – MxNx3
version (None) – reserved for future use
- Returns
cropped image scaled to 0.0 to 1.0 (MxN) with physical spacing
- Return type
itkImage[itk.F,2]
itkpocus.sonoque module
- itkpocus.sonoque.load_and_preprocess_image(fp, version=None)[source]
Loads Sonoque .dcm image. Crops to ultrasound data (e.g. removes rulers) and uses a masked median filter to remove any overlayed text (by masking out bright white).
Returns and itk.Image[itk.F,2] with intensities 0 to 1.0 and correct physical spacing.
- Parameters
fp (str) – filepath
version (None) – reserved for future use
- Returns
img (itk.Image[it.F,2])
meta (dict) – Meta dictionary
- itkpocus.sonoque.load_and_preprocess_video(fp, version=None)[source]
Loads Sonoque .mov video. Crops to ultrasound data (e.g. removes rulers) and uses a masked median filter to remove any overlayed text (by masking out bright white).
Returns and itk.Image[itk.F,3] with intensities 0 to 1.0 and correct physical spacing.
- Parameters
fp (str) – filepath
version (None) – reserved for future use
- Returns
img (itk.Image[itk.F,2])
meta (dict) – Meta data dictionary
itkpocus.sonosite module
- itkpocus.sonosite.load_and_preprocess_image(fp, version=None)[source]
Loads Sonosite .jpg image. Crops to ultrasound data (e.g. removes rulers) and uses a masked median filter to remove any overlayed text (by masking out bright white).
Returns and itk.Image[itk.F,2] with intensities 0 to 1.0 and correct physical spacing.
- Parameters
fp (str) – filepath
version (None) – reserved for future use
- Returns
img (itk.Image[it.F,2])
meta (dict) – Meta dictionary
- itkpocus.sonosite.load_and_preprocess_video(fp, version=None)[source]
Loads Sonosite .mp4 video. Crops to ultrasound data (e.g. removes rulers) and uses a masked median filter to remove any overlayed text (by masking out bright white).
Returns and itk.Image[itk.F,3] with intensities 0 to 1.0 and correct physical spacing.
- Parameters
fp (str) – filepath
version (None) – reserved for future use
- Returns
img (itk.Image[itk.F,2])
meta (dict) – Meta data dictionary
- itkpocus.sonosite.preprocess_image(npimg, version=None)[source]
Loads and preprocesses a Sonosite image.
- Parameters
npimg (ndarray) – MxNx3 image array
version (optional) – Reserved for future use.
- Returns
img (itk.Image[itk.F,2]) – Floating point image with physical spacing set, origin is at upper-left of image, and intensities are between 0.0 and 1.0
meta (dict) – Meta data (includes spacing and crop)
- itkpocus.sonosite.preprocess_video(npvid, framerate=1, version=None)[source]
Loads and preprocesses a Sonosite video.
- Parameters
ndarray (ndarray) – FxMxNxRGB
version (optional) – Reserved for future use.
- Returns
img (itk.Image[itk.F,3]) – Floating point image with physical spacing set (3rd dimension is framerate), origin is at upper-left of image, and intensities are between 0.0 and 1.0
meta (dict) – Meta data (includes spacing and crop)
itkpocus.util module
- itkpocus.util.array_from_image(img, return_meta=False)[source]
Augment ITK array_from_image so that common parameters are also returned
- Returns
img (itk.Image)
spacing (ndarray, optional) – if return_meta
direction (ndarray, optional) – if return_meta
origin (ndarray, optional) – if return_meta
- itkpocus.util.array_from_spatial(obj, size, inside_value=1, outside_value=0)[source]
Return a Numpy array image of an ITKSpatialOjbect
- objitk.SpatialObject or list of itk.SpatialObject
spatial object(s) to convert to mask image, should be in index (i.e. spacing = 1.0, origin = 0.0) coordinates
- sizendarray
size in x and y (columns, rows)
- inside_valuefloat or list of float
value to assign interior of each mask, if real, same value for each mask
- outside_valuefloat
value to assign background
- Returns
- Return type
ndarray
- itkpocus.util.crop(npimg, crop, rgb=False)[source]
Crops the ndarray denoted by npimg according to rows and columns specified in crop.
- Parameters
npimg (ndarray) – [Tx]xMxNx[RGB]
crop (ndarray) – [[topmost, bottommost], [lefmost, rightmost]]
rgb (bool) – whether it is an rgb img
- itkpocus.util.extract_slice(img, slice_, axis=2)[source]
Returns a 2D frame from a 3D image (assumes itk.F pixels)
Adds frame to the index of the largest possible region according to the selected axis. Direction submatrix is maintained in returned frame image.
- Parameters
img (itk.Image[itk.F,3]) – 3D ITK image
slice (int) – the frame/slice to get
axis (ndarray) – a binary array of size dim specifing which index to slice along, the default assumes typical z-axis index
- itkpocus.util.get_framerate(meta_dict)[source]
Returns the framerate as a float from a meta_dict from ffprobe.
- Parameters
meta_dict (dict) –
- Returns
- Return type
float
- itkpocus.util.image_from_array(array, spacing=None, direction=None, origin=None, reference_image=None)[source]
Augment ITK image_from_array so common parameters can be set in one line
- Parameters
array (ndarray) –
spacing (ndarray, optional) –
direction (ndarray, optional) –
origin (ndarray, optional) –
reference_image (ndarray, optional) – if specified, use its spacing, direction, origin
- Returns
- Return type
itk.Image
- itkpocus.util.image_from_spatial(obj, reference_image, inside_value=1, outside_value=0)[source]
Return a mask image from a single or list of ITKSpatialObjects.
- Parameters
obj (itk.SpatialObject or list of itk.SpatialObject) – spatial object(s) to convert to mask image, should be in index (i.e. spacing = 1.0, origin = 0.0) coordinates
reference_image (itk.Image) – sets the spacing, direction, origin, and size of the output image
inside_value (float or list of float) – value to assign interior of each mask, if real, same value for each mask
outside_value (float) –
- Returns
- Return type
itk.Image
- itkpocus.util.operate(img1, img2, foo)[source]
Convenience function for applying a function foo between two images. foo is written on numpy arrays. This function will output ITK arrays or numpy arrays to match the input.
- Parameters
img1 (itk.Image or ndarray) –
img2 (itk.Image or ndarray) –
foo (function) – foo(img1, img2)
- Returns
- Return type
itk.Image or ndarray
- itkpocus.util.overwrite_mask(npimg1, npimg2, outside_value=0)[source]
Combine npimg1 and npimg2 while overwriting any overlap with npimg2’s value.
- Parameters
npimg1 (ndarray) –
npimg2 (ndarray) –
outside_value (float or int, default=0) – elements in npimg2 with value == outside_value will not overwrite npimg1
- Returns
- Return type
ndarray
- itkpocus.util.polgyon_from_array(pts)[source]
Return a PolygonSpatialObject from a list of points defining a closed polygon.
- Parameters
pts (ndarray) – Nx2 open array of polygon points, x0 != xn
- Returns
- Return type
itk.PolygonSpatialObject[2]
- itkpocus.util.transform_to_indices(pts, image)[source]
Transform ITK’s physical locations to [y,x] indices. Note, this is not the same as ITK’s index scheme.
- Parameters
pts (ndarray) – Nx2 physical points [x,y]
image (itk.Image) –
- Returns
Nx2 indices in [row,col], i.e., numpy indexing
- Return type
ndarray
- itkpocus.util.transform_to_physical(indices, image)[source]
Transform [y,x] indices to physical locations in an image. Note, this is not the same as ITK’s index scheme.
- Parameters
indices (ndarray) – Nx2 indices represented as [row,col], i.e., numpy indexing
image (itk.Image) –
- Returns
Nx2 physical points [x,y]
- Return type
ndarray
- itkpocus.util.union_mask(npimg1, npimg2, outside_value=0, inside_value=1)[source]
Combine npimg1 and npimg2 and set the union to inside_value
- Parameters
npimg1 (ndarray) –
npimg2 (ndarray) –
outside_value (float or int, default=0) – defines the background in the mask images
inside_value (float or int, default=1) – defines the value of non-background union
- Returns
- Return type
ndarray
- itkpocus.util.window_sample(x, spacing, num=None)[source]
Randomly sample an array of indices maintaining a minimum distance between samples. For example, when wanting to take frames from a video that are sufficiently separated in time.
- Parameters
x (ndarray of int) – an array of indices such as from np.argwhere
spacing (int) – distance maintained between return indices, i.e., or all x,y in result, \(|x-y| > ext{spacing}\)
num (int) – number of samples to return, or as many as possible if None
- Returns
subsample of x
- Return type
ndarray
Module contents
ITKPOCUS - an open source library for image processing and AI of point-of-care ultrasound, based on ITK (https://pypi.org/project/itk/)