cvkit.pose_estimation.data_readers package

Submodules

cvkit.pose_estimation.data_readers.cvkit_datastore module

class CVKitDataStore3D(body_parts, path, dimensions=3)

Bases: DataStoreInterface

Implements a datastore reader for BU-CVKit’s n-dimensional data files. Expects a csv file where all dimensions are stored in a single cell. The header should contain a single column per keypoint.

Parameters:

• body_parts – list of column names

• path – path to data file

• dimension – data dimension

FLAVOR = 'CVKit3D'

Acts as an ID for the class. File with “CVKit3D” indicates that the file should be opened with CVKitDataStore3D

SEP = ';'

File Separator

build_part(row, name)

Build part from internal row representation

Parameters:

• row – row of a dataframe

• name – Name of the part

Returns:

Part Object

build_skeleton(row) → Skeleton

Build skeleton from internal row representation.

Parameters:

row – row of a dataframe.

static convert_to_list(index, skeleton, threshold=0.8)

Generates a list of parts for csv.writer module. The structure of the list depends upon output data format. The data not crossing the threshold will not be included. Can be used to convert one data flavor to another.

Parameters:

• index – Target Index

• skeleton – Target skeleton

• threshold – Threshold for including data.

delete_part(index, name, force_remove=False)

Deletes part at given index.

Parameters:

• index – The index from which the part will be deleted.

• name – Name of the target part.

• force_remove – Bypass index validation.

get_behaviour(index) → list

Get behaviour at given index.

Parameters:

index – The idex of the data to be retrieved.

Returns:

List of behaviours

get_part(index, name) → Part

Get Part object at given index.

Parameters:

• index – The index from which the data will be retrieved.

• name – Name of the target body part.

Returns:

Part

get_part_slice(slice_indices: list, name: str) → ndarray

Get slice of data for given part as a Numpy array.

Parameters:

• slice_indices – List of two integers defining starting and ending point (non-inclusive) of the slice.

• name – Name of the body part

Returns:

Numpy array of dimension nxd where n is the size of the slice and d is the dimension of the data.

save_file(path: str | None = None) → None

Save data to a file.

Parameters:

path – Path of the file. If None, the file will overwrite.

set_behaviour(index, behaviour: list) → None

Set behaviour data for current index.

Parameters:

• index – The index where behaviour data will be inserted.

• behaviour – List of behaviours

set_part(index, part: Part) → None

Set Part object at given index.

Parameters:

• index – The index at which the data will be inserted.

• part – Part to be inserted.

set_part_slice(slice_indices: list, name: str, data: ndarray) → None

Set a slice of data for given part.

Parameters:

• slice_indices – List of two integers defining starting and ending point (non-inclusive) of the slice.

• name – Name of the body part

• data – nxd dimensional numpy array where n is the size of the slice and d is the dimension of the data.

cvkit.pose_estimation.data_readers.datastore_interface module

class DataStoreInterface(body_parts, path, dimension=3)

Bases: ABC

Interface for data reader. This class can be implemented to integrate data files from other toolkits.

Parameters:

• body_parts – list of column names

• path – path to data file

• dimension – data dimension

BEHAVIOUR_SEP = '~'

Character to separate multiple behaviours

DIMENSIONS = 3

Dimension of the data

FLAVOR = 'Abstract'

Acts as an ID for the class. File with “CVKit3D” indicates that the file should be opened with CVKitDataStore3D

MAGIC_NUMBER = -4668

Magic number to represent invalid data

SEP = ','

File Separator

build_empty_skeleton()

Builds empty skeleton object from a pre-defined MAGIC_NUMBER.

Returns:

Empty Skeleton

abstract build_part(row, name) → Part

Build part from internal row representation

Parameters:

• row – row of a dataframe

• name – Name of the part

Returns:

Part Object

abstract build_skeleton(row) → Skeleton

Build skeleton from internal row representation.

Parameters:

row – row of a dataframe.

compute_data_hash()

Computes a hash value of the dataframe. Used to detect changes.

Returns:

hash value

abstract static convert_to_list(index, skeleton, threshold=0.8)

Generates a list of parts for csv.writer module. The structure of the list depends upon output data format. The data not crossing the threshold will not be included. Can be used to convert one data flavor to another.

Parameters:

• index – Target Index

• skeleton – Target skeleton

• threshold – Threshold for including data.

abstract delete_part(index, name, force_remove=False)

Deletes part at given index.

Parameters:

• index – The index from which the part will be deleted.

• name – Name of the target part.

• force_remove – Bypass index validation.

delete_skeleton(index)

Deletes data at location pointed by the index.

Parameters:

index – The index of the data to be deleted

abstract get_behaviour(index) → list[str]

Get behaviour at given index.

Parameters:

index – The idex of the data to be retrieved.

Returns:

List of behaviours

get_header_rows()

Generates a list of header data for csv.writer module. The structure of the list depends upon output data format.

Returns:

List of header data

Return type:

list

get_numpy(index)

Generate nxd Numpy array from given index where n is number of body parts and d is the dimension. The order of data follows DataStoreInterface.body_parts.

Parameters:

index – The index from which data will be retrieved.

Returns:

nxd Numpy array

abstract get_part(index, name) → Part

Get Part object at given index.

Parameters:

• index – The index from which the data will be retrieved.

• name – Name of the target body part.

Returns:

Part

abstract get_part_slice(slice_indices: list[int], name: str) → ndarray

Get slice of data for given part as a Numpy array.

Parameters:

• slice_indices – List of two integers defining starting and ending point (non-inclusive) of the slice.

• name – Name of the body part

Returns:

Numpy array of dimension nxd where n is the size of the slice and d is the dimension of the data.

get_skeleton(index) → Skeleton

Generates and return skeleton object for the frame defined by index.

Parameters:

index – The index number pointing to the data corresponding to the frame.

Returns:

Skeleton object

part_iterator(part)

Generates and iterator which yields index and corresponding Part sequentially. Example Usage: .. highlight:: python .. code-block:: python

for index, snout in data_store.part_iterator(‘snout’):

print(index,snout)

Parameters:

part – Target body part.

row_iterator()

Generates and iterator which yields index and corresponding Skeleton sequentially.

Example Usage:

for index, skeleton in data_store.row_iterator():
    print(index,skeleton)

save_file(path: str | None = None) → None

Save data to a file.

Parameters:

path – Path of the file. If None, the file will overwrite.

abstract set_behaviour(index, behaviour: list[str]) → None

Set behaviour data for current index.

Parameters:

• index – The index where behaviour data will be inserted.

• behaviour – List of behaviours

abstract set_part(index, part: Part) → None

Set Part object at given index.

Parameters:

• index – The index at which the data will be inserted.

• part – Part to be inserted.

abstract set_part_slice(slice_indices: list, name: str, data: ndarray) → None

Set a slice of data for given part.

Parameters:

• slice_indices – List of two integers defining starting and ending point (non-inclusive) of the slice.

• name – Name of the body part

• data – nxd dimensional numpy array where n is the size of the slice and d is the dimension of the data.

set_skeleton(index, skeleton: Skeleton, force_insert=False) → None

Set pose data from :py:class`~cvkit.pose_estimation.skeleton.Skeleton` object at given index.

Parameters:

• index – The index at which the data will be inserted.

• skeleton – Skeleton object containing the pose data.

• force_insert – By pass index validation

set_stats(stats)

Set datastore statistics object (DataStoreStats).

Parameters:

stats – DataStoreStats object

verify_stats()

Verify whether current datastore statistics are valid.

Returns:

datastore statistics validity

Return type:

boolean

cvkit.pose_estimation.data_readers.deeplabcut_datastore module

class DeeplabcutDataStore(body_parts, path, dimensions=2)

Bases: DataStoreInterface

Implements a datastore reader for DeepLabCut compatible data files.

Parameters:

• body_parts – list of column names

• path – path to data file

• dimension – data dimension

DIMENSIONS = 2

Dimension of the data

FLAVOR = 'deeplabcut'

Acts as an ID for the class. File with “CVKit3D” indicates that the file should be opened with CVKitDataStore3D

build_part(row, name)

Build part from internal row representation

Parameters:

• row – row of a dataframe

• name – Name of the part

Returns:

Part Object

build_skeleton(row) → Skeleton

Build skeleton from internal row representation.

Parameters:

row – row of a dataframe.

static convert_to_list(index, skeleton, threshold=0.8)

Generates a list of parts for csv.writer module. The structure of the list depends upon output data format. The data not crossing the threshold will not be included. Can be used to convert one data flavor to another.

Parameters:

• index – Target Index

• skeleton – Target skeleton

• threshold – Threshold for including data.

delete_part(index, name, force_remove=False)

Deletes part at given index.

Parameters:

• index – The index from which the part will be deleted.

• name – Name of the target part.

• force_remove – Bypass index validation.

get_behaviour(index) → list

Get behaviour at given index.

Parameters:

index – The idex of the data to be retrieved.

Returns:

List of behaviours

get_part(index, name) → Part

Get Part object at given index.

Parameters:

• index – The index from which the data will be retrieved.

• name – Name of the target body part.

Returns:

Part

get_part_slice(slice_indices: list, name: str) → ndarray

Get slice of data for given part as a Numpy array.

Parameters:

• slice_indices – List of two integers defining starting and ending point (non-inclusive) of the slice.

• name – Name of the body part

Returns:

Numpy array of dimension nxd where n is the size of the slice and d is the dimension of the data.

part_iterator(part)

Generates and iterator which yields index and corresponding Part sequentially. Example Usage: .. highlight:: python .. code-block:: python

for index, snout in data_store.part_iterator(‘snout’):

print(index,snout)

Parameters:

part – Target body part.

set_behaviour(index, behaviour) → None

Set behaviour data for current index.

Parameters:

• index – The index where behaviour data will be inserted.

• behaviour – List of behaviours

set_part(index, part: Part) → None

Set Part object at given index.

Parameters:

• index – The index at which the data will be inserted.

• part – Part to be inserted.

set_part_slice(slice_indices: list, name: str, data: ndarray) → None

Set a slice of data for given part.

Parameters:

• slice_indices – List of two integers defining starting and ending point (non-inclusive) of the slice.

• name – Name of the body part

• data – nxd dimensional numpy array where n is the size of the slice and d is the dimension of the data.

cvkit.pose_estimation.data_readers.flattened_datastore module

class FlattenedDataStore(body_parts, path, dimension=3)

Bases: DataStoreInterface

Implements a datastore reader for flattened csv files. Expects a csv file where all dimensions are flattened. The header should contain 3 consecutive columns per keypoint. Ex. Snout_1,Snout_2,Snout_3 for x,y, and z values

Parameters:

• body_parts – list of column names

• path – path to data file

• dimension – data dimension

DIMENSIONS = 3

Dimension of the data

FLAVOR = 'flattened'

Acts as an ID for the class. File with “CVKit3D” indicates that the file should be opened with CVKitDataStore3D

build_part(row, name)

Build part from internal row representation

Parameters:

• row – row of a dataframe

• name – Name of the part

Returns:

Part Object

build_skeleton(row) → Skeleton

Build skeleton from internal row representation.

Parameters:

row – row of a dataframe.

static convert_to_list(index, skeleton, threshold=0.8)

Generates a list of parts for csv.writer module. The structure of the list depends upon output data format. The data not crossing the threshold will not be included. Can be used to convert one data flavor to another.

Parameters:

• index – Target Index

• skeleton – Target skeleton

• threshold – Threshold for including data.

delete_part(index, name, force_remove=False)

Deletes part at given index.

Parameters:

• index – The index from which the part will be deleted.

• name – Name of the target part.

• force_remove – Bypass index validation.

get_behaviour(index) → list

Get behaviour at given index.

Parameters:

index – The idex of the data to be retrieved.

Returns:

List of behaviours

get_header_rows()

Generates a list of header data for csv.writer module. The structure of the list depends upon output data format.

Returns:

List of header data

Return type:

list

get_part(index, name) → Part

Get Part object at given index.

Parameters:

• index – The index from which the data will be retrieved.

• name – Name of the target body part.

Returns:

Part

get_part_slice(slice_indices: list, name: str) → ndarray

Get slice of data for given part as a Numpy array.

Parameters:

• slice_indices – List of two integers defining starting and ending point (non-inclusive) of the slice.

• name – Name of the body part

Returns:

Numpy array of dimension nxd where n is the size of the slice and d is the dimension of the data.

part_iterator(part)

Generates and iterator which yields index and corresponding Part sequentially. Example Usage: .. highlight:: python .. code-block:: python

for index, snout in data_store.part_iterator(‘snout’):

print(index,snout)

Parameters:

part – Target body part.

save_file(path: str | None = None) → None

Save data to a file.

Parameters:

path – Path of the file. If None, the file will overwrite.

set_behaviour(index, behaviour: list) → None

Set behaviour data for current index.

Parameters:

• index – The index where behaviour data will be inserted.

• behaviour – List of behaviours

set_part(index, part: Part) → None

Set Part object at given index.

Parameters:

• index – The index at which the data will be inserted.

• part – Part to be inserted.

set_part_slice(slice_indices: list, name: str, data: ndarray) → None

Set a slice of data for given part.

Parameters:

• slice_indices – List of two integers defining starting and ending point (non-inclusive) of the slice.

• name – Name of the body part

• data – nxd dimensional numpy array where n is the size of the slice and d is the dimension of the data.

Module contents

convert_data_flavor(source: DataStoreInterface, target: DataStoreInterface)

Converts one data flavor to another.

Parameters:

• source (DataStoreInterface.) – Source datastore instance.

• target (DataStoreInterface) – Empty target datastore instance.

initialize_datastore_reader(body_parts, path, reader_type, dimension=3) → DataStoreInterface

Detects underlying class based on reader_type. And generates appropriate DataStoreInterface subclass instance.

Parameters:

• body_parts (list[str]) – List of body parts

• path (str) – Path to the data file

• reader_type (str) – A string to identify underlying data reader type. Refer to the FLAVOR attributes of each implementation.

• dimension (int) – Dimension of the data

Returns:

An instance of appropriate subclass of DataStoreInterface.

Return type:

DataStoreInterface