RegionResource

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

@dataclass
class RegionResource:
    res_id: str
    label: str
    color: str
    region_of: str
    geometry: dict[str, Any]
    comments: list[str]
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
    migration_metadata: MigrationMetadata | None = None

    def __post_init__(self) -> None:
        _check_strings(string_to_check=self.res_id, res_id=self.res_id, field_name="Resource ID")
        _check_strings(string_to_check=self.label, res_id=self.res_id, field_name="Label")
        if not is_color(self.color):
            msg = (
                f"The color value '{self.color}' for the resource with the ID: '{self.res_id}' failed validation. "
                f"Please consult the documentation for details."
            )
            warnings.warn(DspToolsUserWarning(msg))
        if fail_msg := find_geometry_problem(self.geometry):
            msg = f"The geometry of the resource with the ID '{self.res_id}' failed validation.\n" + fail_msg
            warnings.warn(DspToolsUserWarning(msg))

    @staticmethod
    def create_new(
        res_id: str,
        label: str,
        color: str,
        region_of: str,
        geometry: dict[str, Any],
        comments: Collection[str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    ) -> RegionResource:
        """
        Creates a new region resource.
        A region is a region of interest (ROI) in a StillImageRepresentation.

        [See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#region)

        Args:
            res_id: ID of this region resource
            label: label of this region resource
            color: color of the region, as `#` followed by 3 or 6 hex numerals (cardinality 1)
                   ([See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#color))
            region_of: ID of the image resource that this region refers to (cardinality 1)
            geometry: geometry information of the region (cardinality 1)
                      ([See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#geometry))
            comments: comments to this region (cardinality 1-n)
            permissions: permissions of this region resource

        Returns:
            A region resource
        """
        return RegionResource(
            res_id=res_id,
            label=label,
            color=color,
            region_of=region_of,
            geometry=geometry,
            comments=list(comments),
            permissions=permissions,
        )

    def add_comment(self, comment: str) -> RegionResource:
        """
        Add a comment to the resource

        Args:
            comment: text

        Returns:
            The original resource, with the added comment
        """
        self.comments.append(comment)
        return self

    def add_comment_multiple(self, comments: Collection[str]) -> RegionResource:
        """
        Add several comments to the resource

        Args:
            comments: list of texts

        Returns:
            The original resource, with the added comments
        """
        self.comments.extend(comments)
        return self

    def add_comment_optional(self, comment: Any) -> RegionResource:
        """
        If the value is not empty, add it as comment, otherwise return the resource unchanged.

        Args:
            comment: text or empty value

        Returns:
            The original resource, with the added comment
        """
        if is_nonempty_value(comment):
            self.comments.append(comment)
        return self

    def add_migration_metadata(
        self, creation_date: str | None, iri: str | None = None, ark: str | None = None
    ) -> RegionResource:
        """
        Add metadata from a SALSAH migration.

        Args:
            creation_date: creation date of the resource in SALSAH
            iri: Original IRI in SALSAH
            ark: Original ARK in SALSAH

        Raises:
            InputError: if metadata already exists

        Returns:
            The original resource, with the added metadata
        """
        if self.migration_metadata:
            raise InputError(
                f"The resource with the ID '{self.res_id}' already contains migration metadata, "
                f"no new data can be added."
            )
        self.migration_metadata = MigrationMetadata(creation_date=creation_date, iri=iri, ark=ark, res_id=self.res_id)
        return self

    def serialise(self) -> etree._Element:
        self.comments = _transform_unexpected_input(self.comments, "comments", self.res_id)
        res_ele = self._serialise_resource_element()
        res_ele.append(self._serialise_geometry())
        res_ele.extend(self._serialise_values())
        if self.comments:
            res_ele.append(_serialise_has_comment(self.comments, self.res_id))
        return res_ele

    def _serialise_resource_element(self) -> etree._Element:
        attribs = {"label": self.label, "id": self.res_id}
        if self.permissions != Permissions.PROJECT_SPECIFIC_PERMISSIONS:
            attribs["permissions"] = self.permissions.value
        return etree.Element(f"{DASCH_SCHEMA}region", attrib=attribs, nsmap=XML_NAMESPACE_MAP)

    def _serialise_values(self) -> list[etree._Element]:
        return [
            ColorValue(value=self.color, prop_name="hasColor", resource_id=self.res_id).serialise(),
            LinkValue(value=self.region_of, prop_name="isRegionOf", resource_id=self.res_id).serialise(),
        ]

    def _serialise_geometry(self) -> etree._Element:
        geo_prop = etree.Element(f"{DASCH_SCHEMA}geometry-prop", name="hasGeometry", nsmap=XML_NAMESPACE_MAP)
        ele = etree.Element(f"{DASCH_SCHEMA}geometry", nsmap=XML_NAMESPACE_MAP)
        ele.text = str(self.geometry)
        geo_prop.append(ele)
        return geo_prop

create_new

Creates a new region resource. A region is a region of interest (ROI) in a StillImageRepresentation.

See XML documentation for details

Parameters:

Name	Type	Description	Default
res_id	str	ID of this region resource	required
label	str	label of this region resource	required
color	str	color of the region, as # followed by 3 or 6 hex numerals (cardinality 1) (See XML documentation for details)	required
region_of	str	ID of the image resource that this region refers to (cardinality 1)	required
geometry	dict[str, Any]	geometry information of the region (cardinality 1) (See XML documentation for details)	required
comments	Collection[str]	comments to this region (cardinality 1-n)	required
permissions	Permissions	permissions of this region resource	PROJECT_SPECIFIC_PERMISSIONS

Returns:

Type	Description
RegionResource	A region resource

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

@staticmethod
def create_new(
    res_id: str,
    label: str,
    color: str,
    region_of: str,
    geometry: dict[str, Any],
    comments: Collection[str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
) -> RegionResource:
    """
    Creates a new region resource.
    A region is a region of interest (ROI) in a StillImageRepresentation.

    [See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#region)

    Args:
        res_id: ID of this region resource
        label: label of this region resource
        color: color of the region, as `#` followed by 3 or 6 hex numerals (cardinality 1)
               ([See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#color))
        region_of: ID of the image resource that this region refers to (cardinality 1)
        geometry: geometry information of the region (cardinality 1)
                  ([See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#geometry))
        comments: comments to this region (cardinality 1-n)
        permissions: permissions of this region resource

    Returns:
        A region resource
    """
    return RegionResource(
        res_id=res_id,
        label=label,
        color=color,
        region_of=region_of,
        geometry=geometry,
        comments=list(comments),
        permissions=permissions,
    )

add_comment

Add a comment to the resource

Parameters:

Name	Type	Description	Default
comment	str	text	required

Returns:

Type	Description
RegionResource	The original resource, with the added comment

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_comment(self, comment: str) -> RegionResource:
    """
    Add a comment to the resource

    Args:
        comment: text

    Returns:
        The original resource, with the added comment
    """
    self.comments.append(comment)
    return self

add_comment_multiple

Add several comments to the resource

Parameters:

Name	Type	Description	Default
comments	Collection[str]	list of texts	required

Returns:

Type	Description
RegionResource	The original resource, with the added comments

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_comment_multiple(self, comments: Collection[str]) -> RegionResource:
    """
    Add several comments to the resource

    Args:
        comments: list of texts

    Returns:
        The original resource, with the added comments
    """
    self.comments.extend(comments)
    return self

add_comment_optional

If the value is not empty, add it as comment, otherwise return the resource unchanged.

Parameters:

Name	Type	Description	Default
comment	Any	text or empty value	required

Returns:

Type	Description
RegionResource	The original resource, with the added comment

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_comment_optional(self, comment: Any) -> RegionResource:
    """
    If the value is not empty, add it as comment, otherwise return the resource unchanged.

    Args:
        comment: text or empty value

    Returns:
        The original resource, with the added comment
    """
    if is_nonempty_value(comment):
        self.comments.append(comment)
    return self

add_migration_metadata

Add metadata from a SALSAH migration.

Parameters:

Name	Type	Description	Default
creation_date	str | None	creation date of the resource in SALSAH	required
iri	str | None	Original IRI in SALSAH	None
ark	str | None	Original ARK in SALSAH	None

Returns:

Type	Description
RegionResource	The original resource, with the added metadata

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py

def add_migration_metadata(
    self, creation_date: str | None, iri: str | None = None, ark: str | None = None
) -> RegionResource:
    """
    Add metadata from a SALSAH migration.

    Args:
        creation_date: creation date of the resource in SALSAH
        iri: Original IRI in SALSAH
        ark: Original ARK in SALSAH

    Raises:
        InputError: if metadata already exists

    Returns:
        The original resource, with the added metadata
    """
    if self.migration_metadata:
        raise InputError(
            f"The resource with the ID '{self.res_id}' already contains migration metadata, "
            f"no new data can be added."
        )
    self.migration_metadata = MigrationMetadata(creation_date=creation_date, iri=iri, ark=ark, res_id=self.res_id)
    return self