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
.
- 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¶
- 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:
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()
- 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')
- _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]
- 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
- class kwcoco.coco_objects1d.Categories(ids, dset)[source]¶
Bases:
ObjectList1D
Vectorized access to category attributes
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
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']
- 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
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 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]]))>
- class kwcoco.coco_objects1d.Tracks(ids, dset)[source]¶
Bases:
ObjectList1D
Vectorized access to track attributes
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