kwcoco.coco_objects1d module¶

Vectorized ORM-like objects used in conjunction with coco_dataset.

This powers the .images(), .videos(), and .annotation() methods of kwcoco.CocoDataset.

Todo

[ ] The use of methods vs properties is inconsistent. This needs to be fixed, but backwards compatability is a consideration.

See:: kwcoco.coco_dataset.MixinCocoObjects.categories() kwcoco.coco_dataset.MixinCocoObjects.videos() kwcoco.coco_dataset.MixinCocoObjects.images() kwcoco.coco_dataset.MixinCocoObjects.annots() kwcoco.coco_dataset.MixinCocoObjects.tracks()

class kwcoco.coco_objects1d.ObjectList1D(ids, dset, key)[source]¶

Bases: NiceRepr

Vectorized access to lists of dictionary objects

Lightweight reference to a set of object (e.g. annotations, images) that allows for convenient property access.

Types:: ObjT = Ann | Img | Cat # can be one of these types ObjectList1D gives us access to a List[ObjT]

Example

>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo()
>>> # Both annots and images are object lists
>>> self = dset.annots()
>>> self = dset.images()
>>> # can call with a list of ids or not, for everything
>>> self = dset.annots([1, 2, 11])
>>> self = dset.images([1, 2, 3])
>>> self.lookup('id')
>>> self.lookup(['id'])

Parameters:

ids (List[int]) – list of ids
dset (CocoDataset) – parent dataset
key (str) – main object name (e.g. ‘images’, ‘annotations’)

property _id_to_obj¶

unique()[source]¶

Removes any duplicates entries in this object

Returns:: ObjectList1D

property ids¶: Returns: List[int]

property objs¶

Get the underlying object dictionary for each object.

Returns:: all object dictionaries
Return type:: List[ObjT]

take(idxs)[source]¶

Take a subset by index

Returns:: ObjectList1D

Example

>>> import kwcoco
>>> self = kwcoco.CocoDataset.demo().annots()
>>> assert len(self.take([0, 2, 3])) == 3

compress(flags)[source]¶

Take a subset by flags

Returns:: ObjectList1D

Example

>>> import kwcoco
>>> self = kwcoco.CocoDataset.demo().images()
>>> assert len(self.compress([True, False, True])) == 2

peek()[source]¶

Return the first object dictionary

Returns:: object dictionary
Return type:: ObjT

Example

>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo()
>>> self = dset.images()
>>> assert self.peek()['id'] == 1
>>> # Check that subsets return correct items
>>> sub0 = self.compress([i % 2 == 0 for i in range(len(self))])
>>> sub1 = self.compress([i % 2 == 1 for i in range(len(self))])
>>> assert sub0.peek()['id'] == 1
>>> assert sub1.peek()['id'] == 2

lookup(key, default=NoParam, keepid=False)[source]¶

Lookup a list of object attributes

Parameters:

key (str | Iterable) – name of the property you want to lookup can also be a list of names, in which case we return a dict
default – if specified, uses this value if it doesn’t exist in an ObjT.
keepid – if True, return a mapping from ids to the property

Returns:

a list of whatever type the object is Dict[str, ObjT]

Return type:

List[ObjT]

Example

>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo()
>>> self = dset.annots()
>>> self.lookup('id')
>>> key = ['id']
>>> default = None
>>> self.lookup(key=['id', 'image_id'])
>>> self.lookup(key=['id', 'image_id'])
>>> self.lookup(key='foo', default=None, keepid=True)
>>> self.lookup(key=['foo'], default=None, keepid=True)
>>> self.lookup(key=['id', 'image_id'], keepid=True)

sort_values(by, reverse=False, key=None)[source]¶

Reorders the items by an attribute.

Parameters:

by (str) – The column attribute to sort by
key (Callable | None) – Apply the key function to the values before sorting.

Returns:

copy of this object with new ids

Return type:

ObjectList1D

Example

>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo('vidshapes8')
>>> self = dset.images()
>>> new = self.sort_values('frame_index')
>>> frame_idxs = new.lookup('frame_index')
>>> assert sorted(frame_idxs) == frame_idxs

get(key, default=NoParam, keepid=False)[source]¶

Lookup a list of object attributes

Parameters:

key (str) – name of the property you want to lookup
default – if specified, uses this value if it doesn’t exist in an ObjT.
keepid – if True, return a mapping from ids to the property

Returns:

a list of whatever type the object is

Return type:

Dict[int, Any] | List[Any]

Example

>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo()
>>> self = dset.annots()
>>> self.get('id')
>>> self.get(key='foo', default=None, keepid=True)

Example

>>> # xdoctest: +REQUIRES(module:sqlalchemy)
>>> import kwcoco
>>> dct_dset = kwcoco.CocoDataset.demo('vidshapes8', rng=303232)
>>> dct_dset.anns[3]['blorgo'] = 3
>>> dct_dset.annots().lookup('blorgo', default=None)
>>> for a in dct_dset.anns.values():
...     a['wizard'] = '10!'
>>> dset = dct_dset.view_sql(force_rewrite=1)
>>> assert dset.anns[3]['blorgo'] == 3
>>> assert dset.anns[3]['wizard'] == '10!'
>>> assert 'blorgo' not in dset.anns[2]
>>> dset.annots().lookup('blorgo', default=None)
>>> dset.annots().lookup('wizard', default=None)
>>> import pytest
>>> with pytest.raises(KeyError):
>>>     dset.annots().lookup('blorgo')
>>> dset.annots().lookup('wizard')
>>> #self = dset.annots()

_iter_get(key, default=NoParam)[source]¶: Iterator version of get, not in stable API yet.

set(key, values)[source]¶

Assign a value to each annotation

Parameters:

key (str) – the annotation property to modify
values (Iterable | Any) – an iterable of values to set for each annot in the dataset. If the item is not iterable, it is assigned to all objects.

Example

>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo()
>>> self = dset.annots()
>>> self.set('my-key1', 'my-scalar-value')
>>> self.set('my-key2', np.random.rand(len(self)))
>>> print('dset.imgs = {}'.format(ub.urepr(dset.imgs, nl=1)))
>>> self.get('my-key2')

_set(key, values)[source]¶: faster less safe version of set

_lookup(key, default=NoParam)[source]¶

Example

>>> # xdoctest: +REQUIRES(--benchmark)
>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo('shapes256')
>>> self = annots = dset.annots()
>>> #
>>> import timerit
>>> ti = timerit.Timerit(100, bestof=10, verbose=2)
>>> #
>>> for timer in ti.reset('lookup'):
>>>     with timer:
>>>         self.lookup('image_id')
>>> #
>>> for timer in ti.reset('_lookup'):
>>>     with timer:
>>>         self._lookup('image_id')
>>> #
>>> for timer in ti.reset('image_id'):
>>>     with timer:
>>>         self.image_id
>>> #
>>> for timer in ti.reset('raw1'):
>>>     with timer:
>>>         key = 'image_id'
>>>         [self._dset.anns[_id][key] for _id in self._ids]
>>> #
>>> for timer in ti.reset('raw2'):
>>>     with timer:
>>>         anns = self._dset.anns
>>>         key = 'image_id'
>>>         [anns[_id][key] for _id in self._ids]
>>> #
>>> for timer in ti.reset('lut-gen'):
>>>     with timer:
>>>         _lut = self._obj_lut
>>>         objs = (_lut[_id] for _id in self._ids)
>>>         [obj[key] for obj in objs]
>>> #
>>> for timer in ti.reset('lut-gen-single'):
>>>     with timer:
>>>         _lut = self._obj_lut
>>>         [_lut[_id][key] for _id in self._ids]

attribute_frequency()[source]¶

Compute the number of times each key is used in a dictionary

Returns:: Dict[str, int]

Example

>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo()
>>> self = dset.annots()
>>> attrs = self.attribute_frequency()
>>> print('attrs = {}'.format(ub.urepr(attrs, nl=1)))

class kwcoco.coco_objects1d.ObjectGroups(groups, dset)[source]¶

Bases: NiceRepr

An object for holding a groups of ObjectList1D objects

Parameters:

groups (List[ObjectList1D]) – list of object lists
dset (CocoDataset) – parent dataset

_lookup(key)[source]¶

lookup(key, default=NoParam)[source]¶

class kwcoco.coco_objects1d.Categories(ids, dset)[source]¶

Bases: ObjectList1D

Vectorized access to category attributes

SeeAlso:: kwcoco.coco_dataset.MixinCocoObjects.categories()

Example

>>> from kwcoco.coco_objects1d import Categories  # NOQA
>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo()
>>> ids = list(dset.cats.keys())
>>> self = Categories(ids, dset)
>>> print('self.name = {!r}'.format(self.name))
>>> print('self.supercategory = {!r}'.format(self.supercategory))

Parameters:

ids (List[int]) – list of category ids
dset (CocoDataset) – parent dataset

property cids¶

property name¶

property supercategory¶

class kwcoco.coco_objects1d.Videos(ids, dset)[source]¶

Bases: ObjectList1D

Vectorized access to video attributes

SeeAlso:: kwcoco.coco_dataset.MixinCocoObjects.videos()

Example

>>> from kwcoco.coco_objects1d import Videos  # NOQA
>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo('vidshapes5')
>>> ids = list(dset.index.videos.keys())
>>> self = Videos(ids, dset)
>>> print('self = {!r}'.format(self))
self = <Videos(num=5) at ...>

Parameters:

ids (List[int]) – list of video ids
dset (CocoDataset) – parent dataset

property images¶

Returns:: ImageGroups

Example

>>> import kwcoco
>>> self = kwcoco.CocoDataset.demo('vidshapes8').videos()
>>> print(self.images)
<ImageGroups(n=8, m=2.0, s=0.0)>

class kwcoco.coco_objects1d.Images(ids, dset)[source]¶

Bases: ObjectList1D

Vectorized access to image attributes

Example

>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo('photos')
>>> images = dset.images()
>>> print('images = {}'.format(images))
images = <Images(num=3)...>
>>> print('images.gname = {}'.format(images.gname))
images.gname = ['astro.png', 'carl.jpg', 'stars.png']

SeeAlso:: kwcoco.coco_dataset.MixinCocoObjects.images()

Parameters:

ids (List[int]) – list of image ids
dset (CocoDataset) – parent dataset

property coco_images¶

property gids¶

property gname¶

property gpath¶

property width¶

property height¶

property size¶

Example:

>>> import kwcoco
>>> self = kwcoco.CocoDataset.demo().images()
>>> self._dset._ensure_imgsize()
...
>>> print(self.size)
[(512, 512), (328, 448), (256, 256)]

property area¶

Returns:: List[float]

Example

>>> import kwcoco
>>> self = kwcoco.CocoDataset.demo().images()
>>> self._dset._ensure_imgsize()
...
>>> print(self.area)
[262144, 146944, 65536]

property n_annots¶

Returns:: List[int]

Example

>>> import kwcoco
>>> self = kwcoco.CocoDataset.demo().images()
>>> print(ub.urepr(self.n_annots, nl=0))
[9, 2, 0]

property aids¶

Returns:: List[set]

Example

>>> import kwcoco
>>> self = kwcoco.CocoDataset.demo().images()
>>> print(ub.urepr(list(map(list, self.aids)), nl=0))
[[1, 2, 3, 4, 5, 6, 7, 8, 9], [10, 11], []]

property annots¶

Returns:: AnnotGroups

Example

>>> import kwcoco
>>> self = kwcoco.CocoDataset.demo().images()
>>> print(self.annots)
<AnnotGroups(n=3, m=3.7, s=3.9)>

class kwcoco.coco_objects1d.Annots(ids, dset)[source]¶

Bases: ObjectList1D

Vectorized access to annotation attributes

SeeAlso:: kwcoco.coco_dataset.MixinCocoObjects.annots()

Example

>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo('photos')
>>> annots = dset.annots()
>>> print('annots = {}'.format(annots))
annots = <Annots(num=11)>
>>> image_ids = annots.lookup('image_id')
>>> print('image_ids = {}'.format(image_ids))
image_ids = [1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2]

Parameters:

ids (List[int]) – list of annotation ids
dset (CocoDataset) – parent dataset

property aids¶: The annotation ids of this column of annotations

property images¶

Get the column of images

Returns:: Images

property image_id¶

property category_id¶

property gids¶

Get the column of image-ids

Returns:: list of image ids
Return type:: List[int]

property cids¶

Get the column of category-ids

Returns:: List[int]

property cnames¶

Get the column of category names

Returns:: List[str]

property category_names¶

Get the column of category names

Returns:: List[str]

property detections¶

Get the kwimage-style detection objects

Returns:: kwimage.Detections

Example

>>> # xdoctest: +REQUIRES(module:kwimage)
>>> import kwcoco
>>> self = kwcoco.CocoDataset.demo('shapes32').annots([1, 2, 11])
>>> dets = self.detections
>>> print('dets.data = {!r}'.format(dets.data))
>>> print('dets.meta = {!r}'.format(dets.meta))

property boxes¶

Get the column of kwimage-style bounding boxes

Returns:: kwimage.Boxes

Example

>>> import kwcoco
>>> self = kwcoco.CocoDataset.demo().annots([1, 2, 11])
>>> print(self.boxes)
<Boxes(xywh,
    array([[ 10,  10, 360, 490],
           [350,   5, 130, 290],
           [156, 130,  45,  18]]))>

property xywh¶

Returns raw boxes

DEPRECATED.

Returns:: raw boxes in xywh format
Return type:: List[List[int]]

Example

>>> import kwcoco
>>> self = kwcoco.CocoDataset.demo().annots([1, 2, 11])
>>> print(self.xywh)

class kwcoco.coco_objects1d.Tracks(ids, dset)[source]¶

Bases: ObjectList1D

Vectorized access to track attributes

SeeAlso:: kwcoco.coco_dataset.MixinCocoObjects.tracks()

Example

>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo('vidshapes1', num_tracks=4)
>>> tracks = dset.tracks()
>>> print('tracks = {}'.format(tracks))
tracks = <Tracks(num=4)>
>>> tracks.name
['track_001', 'track_002', 'track_003', 'track_004']

Parameters:

ids (List[int]) – list of track ids
dset (CocoDataset) – parent dataset

property track_ids¶: The annotation ids of this column of annotations

property name¶

property annots¶

Example:

>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo('vidshapes1', num_tracks=4)
>>> self = dset.tracks()
>>> print(self.annots)
<AnnotGroups(n=4, m=2.0, s=0.0)>

class kwcoco.coco_objects1d.AnnotGroups(groups, dset)[source]¶

Bases: ObjectGroups

Annotation groups are vectorized lists of lists.

Each item represents a set of annotations that corresopnds with something (i.e. belongs to a particular image).

Example

>>> from kwcoco.coco_objects1d import ImageGroups
>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo('photos')
>>> images = dset.images()
>>> # Requesting the "annots" property from a Images object
>>> # will return an AnnotGroups object
>>> group: AnnotGroups = images.annots
>>> # Printing the group gives info on the mean/std of the number
>>> # of items per group.
>>> print(group)
<AnnotGroups(n=3, m=3.7, s=3.9)...>
>>> # Groups are fairly restrictive, they dont provide property level
>>> # access in many cases, but the lookup method is available
>>> print(group.lookup('id'))
[[1, 2, 3, 4, 5, 6, 7, 8, 9], [10, 11], []]
>>> print(group.lookup('image_id'))
[[1, 1, 1, 1, 1, 1, 1, 1, 1], [2, 2], []]
>>> print(group.lookup('category_id'))
[[1, 2, 3, 4, 5, 5, 5, 5, 5], [6, 4], []]

Parameters:

groups (List[ObjectList1D]) – list of object lists
dset (CocoDataset) – parent dataset

property cids¶

Get the grouped category ids for annotations in this group

Return type:: List[List[int]]

Example

>>> import kwcoco
>>> self = kwcoco.CocoDataset.demo('photos').images().annots
>>> print('self.cids = {}'.format(ub.urepr(self.cids, nl=0)))
self.cids = [[1, 2, 3, 4, 5, 5, 5, 5, 5], [6, 4], []]

property cnames¶

Get the grouped category names for annotations in this group

Return type:: List[List[str]]

Example

>>> import kwcoco
>>> self = kwcoco.CocoDataset.demo('photos').images().annots
>>> print('self.cnames = {}'.format(ub.urepr(self.cnames, nl=0)))
self.cnames = [['astronaut', 'rocket', 'helmet', 'mouth', 'star', 'star', 'star', 'star', 'star'], ['astronomer', 'mouth'], []]

class kwcoco.coco_objects1d.ImageGroups(groups, dset)[source]¶

Bases: ObjectGroups

Image groups are vectorized lists of other Image objects.

Each item represents a set of images that corresopnds with something (i.e. belongs to a particular video).

Example

>>> from kwcoco.coco_objects1d import ImageGroups
>>> import kwcoco
>>> dset = kwcoco.CocoDataset.demo('vidshapes8')
>>> videos = dset.videos()
>>> # Requesting the "images" property from a Videos object
>>> # will return an ImageGroups object
>>> group: ImageGroups = videos.images
>>> # Printing the group gives info on the mean/std of the number
>>> # of items per group.
>>> print(group)
<ImageGroups(n=8, m=2.0, s=0.0)...>
>>> # Groups are fairly restrictive, they dont provide property level
>>> # access in many cases, but the lookup method is available
>>> print(group.lookup('id'))
[[1, 2], [3, 4], [5, 6], [7, 8], [9, 10], [11, 12], [13, 14], [15, 16]]
>>> print(group.lookup('video_id'))
[[1, 1], [2, 2], [3, 3], [4, 4], [5, 5], [6, 6], [7, 7], [8, 8]]
>>> print(group.lookup('frame_index'))
[[0, 1], [0, 1], [0, 1], [0, 1], [0, 1], [0, 1], [0, 1], [0, 1]]

Parameters:

groups (List[ObjectList1D]) – list of object lists
dset (CocoDataset) – parent dataset