:py:mod:`kwcoco.coco_objects1d` =============================== .. py:module:: kwcoco.coco_objects1d .. autoapi-nested-parse:: Vectorized ORM-like objects used in conjunction with coco_dataset Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: kwcoco.coco_objects1d.ObjectList1D kwcoco.coco_objects1d.ObjectGroups kwcoco.coco_objects1d.Categories kwcoco.coco_objects1d.Videos kwcoco.coco_objects1d.Images kwcoco.coco_objects1d.Annots kwcoco.coco_objects1d.AnnotGroups kwcoco.coco_objects1d.ImageGroups .. py:class:: ObjectList1D(ids, dset, key) Bases: :py:obj:`ubelt.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. :Parameters: * **ids** (*List[int]*) -- list of ids * **dset** (*CocoDataset*) -- parent dataset * **key** (*str*) -- main object name (e.g. 'images', 'annotations') Types: ObjT = Ann | Img | Cat # can be one of these types ObjectList1D gives us access to a List[ObjT] .. rubric:: 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']) .. py:method:: __nice__(self) .. py:method:: __iter__(self) .. py:method:: __len__(self) .. py:method:: _id_to_obj(self) :property: .. py:method:: __getitem__(self, index) .. py:method:: objs(self) :property: :returns: all object dictionaries :rtype: List[ObjT] .. py:method:: take(self, idxs) Take a subset by index :returns: ObjectList1D .. rubric:: Example >>> import kwcoco >>> self = kwcoco.CocoDataset.demo().annots() >>> assert len(self.take([0, 2, 3])) == 3 .. py:method:: compress(self, flags) Take a subset by flags :returns: ObjectList1D .. rubric:: Example >>> import kwcoco >>> self = kwcoco.CocoDataset.demo().images() >>> assert len(self.compress([True, False, True])) == 2 .. py:method:: peek(self) Return the first object dictionary :returns: object dictionary :rtype: ObjT .. rubric:: 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 .. py:method:: lookup(self, key, default=ub.NoParam, keepid=False) 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] :rtype: List[ObjT] .. rubric:: 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) .. py:method:: get(self, key, default=ub.NoParam, keepid=False) 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 Dict[str, ObjT] :rtype: List[ObjT] .. rubric:: Example >>> import kwcoco >>> dset = kwcoco.CocoDataset.demo() >>> self = dset.annots() >>> self.get('id') >>> self.get(key='foo', default=None, keepid=True) .. py:method:: _iter_get(self, key, default=ub.NoParam) Iterator version of get, not in stable API yet. .. py:method:: set(self, key, values) Assign a value to each annotation :Parameters: * **key** (*str*) -- the annotation property to modify * **values** (*Iterable | scalar*) -- an iterable of values to set for each annot in the dataset. If the item is not iterable, it is assigned to all objects. .. rubric:: 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.repr2(dset.imgs, nl=1))) >>> self.get('my-key2') .. py:method:: _set(self, key, values) faster less safe version of set .. py:method:: _lookup(self, key, default=ub.NoParam) .. rubric:: 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] .. py:method:: attribute_frequency(self) Compute the number of times each key is used in a dictionary :returns: Dict[str, int] .. rubric:: Example >>> import kwcoco >>> dset = kwcoco.CocoDataset.demo() >>> self = dset.annots() >>> attrs = self.attribute_frequency() >>> print('attrs = {}'.format(ub.repr2(attrs, nl=1))) .. py:class:: ObjectGroups(groups, dset) Bases: :py:obj:`ubelt.NiceRepr` An object for holding a groups of :class:`ObjectList1D` objects .. py:method:: _lookup(self, key) .. py:method:: __getitem__(self, index) .. py:method:: lookup(self, key, default=ub.NoParam) .. py:method:: __nice__(self) .. py:class:: Categories(ids, dset) Bases: :py:obj:`ObjectList1D` Vectorized access to category attributes SeeAlso: :func:`kwcoco.coco_dataset.MixinCocoObjects.categories` .. rubric:: 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)) .. py:method:: cids(self) :property: .. py:method:: name(self) :property: .. py:method:: supercategory(self) :property: .. py:class:: Videos(ids, dset) Bases: :py:obj:`ObjectList1D` Vectorized access to video attributes SeeAlso: :func:`kwcoco.coco_dataset.MixinCocoObjects.videos` .. rubric:: 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)) .. py:method:: images(self) :property: .. rubric:: Example >>> import kwcoco >>> self = kwcoco.CocoDataset.demo('vidshapes8').videos() >>> print(self.images) .. py:class:: Images(ids, dset) Bases: :py:obj:`ObjectList1D` Vectorized access to image attributes SeeAlso: :func:`kwcoco.coco_dataset.MixinCocoObjects.images` .. py:method:: coco_images(self) :property: .. py:method:: gids(self) :property: .. py:method:: gname(self) :property: .. py:method:: gpath(self) :property: .. py:method:: width(self) :property: .. py:method:: height(self) :property: .. py:method:: size(self) :property: .. rubric:: Example >>> import kwcoco >>> self = kwcoco.CocoDataset.demo().images() >>> self._dset._ensure_imgsize() >>> print(self.size) [(512, 512), (300, 250), (256, 256)] .. py:method:: area(self) :property: .. rubric:: Example >>> import kwcoco >>> self = kwcoco.CocoDataset.demo().images() >>> self._dset._ensure_imgsize() >>> print(self.area) [262144, 75000, 65536] .. py:method:: n_annots(self) :property: .. rubric:: Example >>> import kwcoco >>> self = kwcoco.CocoDataset.demo().images() >>> print(ub.repr2(self.n_annots, nl=0)) [9, 2, 0] .. py:method:: aids(self) :property: .. rubric:: Example >>> import kwcoco >>> self = kwcoco.CocoDataset.demo().images() >>> print(ub.repr2(list(map(list, self.aids)), nl=0)) [[1, 2, 3, 4, 5, 6, 7, 8, 9], [10, 11], []] .. py:method:: annots(self) :property: .. rubric:: Example >>> import kwcoco >>> self = kwcoco.CocoDataset.demo().images() >>> print(self.annots) .. py:class:: Annots(ids, dset) Bases: :py:obj:`ObjectList1D` Vectorized access to annotation attributes SeeAlso: :func:`kwcoco.coco_dataset.MixinCocoObjects.annots` .. py:method:: aids(self) :property: The annotation ids of this column of annotations .. py:method:: images(self) :property: Get the column of images :returns: Images .. py:method:: image_id(self) :property: .. py:method:: category_id(self) :property: .. py:method:: gids(self) :property: Get the column of image-ids :returns: list of image ids :rtype: List[int] .. py:method:: cids(self) :property: Get the column of category-ids :returns: List[int] .. py:method:: cnames(self) :property: Get the column of category names :returns: List[int] .. py:method:: detections(self) :property: Get the kwimage-style detection objects :returns: kwimage.Detections .. rubric:: 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)) .. py:method:: boxes(self) :property: Get the column of kwimage-style bounding boxes .. rubric:: Example >>> import kwcoco >>> self = kwcoco.CocoDataset.demo().annots([1, 2, 11]) >>> print(self.boxes) .. py:method:: xywh(self) :property: Returns raw boxes .. rubric:: Example >>> import kwcoco >>> self = kwcoco.CocoDataset.demo().annots([1, 2, 11]) >>> print(self.xywh) .. py:class:: AnnotGroups(groups, dset) Bases: :py:obj:`ObjectGroups` An object for holding a groups of :class:`ObjectList1D` objects .. py:method:: cids(self) :property: .. py:method:: cnames(self) :property: .. py:class:: ImageGroups(groups, dset) Bases: :py:obj:`ObjectGroups` An object for holding a groups of :class:`ObjectList1D` objects