Source code for geoh5py.groups.group

#  Copyright (c) 2024 Mira Geoscience Ltd.
#
#  This file is part of geoh5py.
#
#  geoh5py is free software: you can redistribute it and/or modify
#  it under the terms of the GNU Lesser General Public License as published by
#  the Free Software Foundation, either version 3 of the License, or
#  (at your option) any later version.
#
#  geoh5py is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU Lesser General Public License for more details.
#
#  You should have received a copy of the GNU Lesser General Public License
#  along with geoh5py.  If not, see <https://www.gnu.org/licenses/>.

from __future__ import annotations

import uuid
from abc import abstractmethod
from datetime import datetime
from typing import TYPE_CHECKING

import numpy as np

from ..data import CommentsData, Data
from ..shared.entity import Entity
from ..shared.entity_container import EntityContainer
from .group_type import GroupType

if TYPE_CHECKING:
    from ..workspace import Workspace


[docs] class Group(EntityContainer): """Base Group class""" def __init__(self, group_type: GroupType, **kwargs): assert group_type is not None self._entity_type = group_type super().__init__(**kwargs)
[docs] @classmethod @abstractmethod def default_type_uid(cls) -> uuid.UUID | None: """Abstract method to return the default type uid for the class."""
[docs] def add_children(self, children: list[Entity]): """ :param children: Add a list of entities as :obj:`~geoh5py.shared.entity.Entity.children` """ if not isinstance(children, list): children = [children] for child in children: if child not in self._children: if not isinstance(child, Entity): raise TypeError( f"Child must be an instance of Entity, not {type(child)}" ) self._children.append(child)
[docs] def add_comment(self, comment: str, author: str | None = None): """ Add text comment to an object. :param comment: Text to be added as comment. :param author: Author's name or :obj:`~geoh5py.workspace.workspace.Workspace.contributors`. """ date = datetime.now().strftime("%Y-%m-%dT%H:%M:%S") if author is None: author = ",".join(self.workspace.contributors) comment_dict = {"Author": author, "Date": date, "Text": comment} if self.comments is None: self.workspace.create_entity( Data, entity={ "name": "UserComments", "association": "OBJECT", "values": [comment_dict], "parent": self, }, entity_type={"primitive_type": "TEXT"}, ) else: self.comments.values = self.comments.values + [comment_dict]
[docs] def mask_by_extent(self, extent: np.ndarray, inverse: bool = False) -> None: """ Sub-class extension of :func:`~geoh5py.shared.entity.Entity.mask_by_extent`. """ return None
[docs] def copy( self, parent=None, copy_children: bool = True, clear_cache: bool = False, mask: np.ndarray | None = None, **kwargs, ): """ Function to copy a group to a different parent entity. :param parent: Target parent to copy the entity under. Copied to current :obj:`~geoh5py.shared.entity.Entity.parent` if None. :param copy_children: (Optional) Create copies of all children entities along with it. :param clear_cache: Clear array attributes after copy. :param mask: Array of bool defining the values to keep. :param kwargs: Additional keyword arguments to pass to the copy constructor. :return entity: Registered Entity to the workspace. """ if parent is None: parent = self.parent new_entity = parent.workspace.copy_to_parent( self, parent, copy_children=False, **kwargs ) if new_entity is None: return None if copy_children: for child in self.children: child.copy( parent=new_entity, copy_children=True, clear_cache=clear_cache, mask=mask, ) return new_entity
[docs] def copy_from_extent( self, extent: np.ndarray, parent=None, copy_children: bool = True, clear_cache: bool = False, inverse: bool = False, **kwargs, ) -> Group | None: """ Sub-class extension of :func:`~geoh5py.shared.entity.Entity.copy_from_extent`. """ copy_group = self.copy( parent=parent, clear_cache=clear_cache, copy_children=False, **kwargs, ) if copy_group is None: return None if copy_children: for child in self.children: child.copy_from_extent( extent, parent=copy_group, copy_children=True, clear_cache=clear_cache, inverse=inverse, ) if len(copy_group.children) == 0: copy_group.workspace.remove_entity(copy_group) return None return copy_group
@property def comments(self): """ Fetch a :obj:`~geoh5py.data.text_data.CommentsData` entity from children. """ for child in self.children: if isinstance(child, CommentsData): return child return None @property def entity_type(self) -> GroupType: return self._entity_type @property def extent(self) -> np.ndarray | None: """ Geography bounding box of the object. :return: shape(2, 3) Bounding box defined by the bottom South-West and top North-East coordinates. """ extents = [] for child in self.children: if child.extent is not None: extents.append(child.extent) if len(extents) > 0: extents = np.vstack(extents) return np.vstack( [ np.min(extents, axis=0), np.max(extents, axis=0), ] ) return None
[docs] @classmethod def find_or_create_type(cls, workspace: Workspace, **kwargs) -> GroupType: kwargs["entity_class"] = cls return GroupType.find_or_create(workspace, **kwargs)