RegionResource

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

@dataclass
class RegionResource:
    res_id: str
    label: str
    region_of: str
    geometry: GeometryShape | None
    comments: list[str] = field(default_factory=list)
    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")

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

        Exactly one geometry shape has to be added to the resource with one of the following methods:
        `add_rectangle`, `add_polygon`, `add_circle` (see documentation below for more information).

        [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
            region_of: ID of the image resource that this region refers to (cardinality 1)
            permissions: permissions of this region resource

        Returns:
            A region resource

        Examples:
            ```python
            region = xmllib.RegionResource.create_new(
                res_id="ID",
                label="label",
                region_of="image_id",
            )
            ```
        """
        return RegionResource(
            res_id=res_id,
            label=label,
            region_of=region_of,
            geometry=None,
            permissions=permissions,
        )

    def add_rectangle(
        self,
        point1: tuple[float, float],
        point2: tuple[float, float],
        line_width: float = 2,
        color: str = "#5b24bf",
        active: bool = True,
    ) -> RegionResource:
        """
        Add a rectangle shape to the region.

        [For a visual example see the XML documentation](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#geometry)

        Args:
            point1: first point of the rectangle represented as two numbers between 0 and 1 in the format (x, y)
            point2: second point of the rectangle represented as two numbers between 0 and 1 in the format (x, y)
            line_width: A number in pixels between 1 - 5
            color: A hexadecimal color value which starts with a `#` followed by 3 or 6 numerals.
                The default value was chosen as it is distinguishable for most color-blind people.
            active: If set to `False`, the region is marked as 'deleted'

        Returns:
            Region with added rectangle

        Examples:
            ```python
            region = region.add_rectangle(
                point1=(0.1, 0.1),
                point2=(0.2, 0.2),
            )
            ```

            ```python
            # with custom display values
            region = region.add_rectangle(
                point1=(0.1, 0.1),
                point2=(0.2, 0.2),
                line_width=3,
                color="#32a873",
            )
            ```
        """
        self.geometry = Rectangle(
            point1=GeometryPoint(point1[0], point1[1], self.res_id),
            point2=GeometryPoint(point2[0], point2[1], self.res_id),
            line_width=line_width,
            color=color,
            active=active,
            resource_id=self.res_id,
        )
        return self

    def add_polygon(
        self,
        points: list[tuple[float, float]],
        line_width: float = 2,
        color: str = "#5b24bf",
        active: bool = True,
    ) -> RegionResource:
        """
        Add a polygon shape to the region.
        A polygon should have at least three points.
        If you wish to create a rectangle, please use the designated `add_rectangle` method.

        [For a visual example see the XML documentation](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#geometry)

        **Please note that this cannot currently be displayed in the dsp-app.**

        Args:
            points: list of tuples containing two numbers between 0 and 1 in the format (x, y)
            line_width: A number in pixels between 1 - 5
            color: A hexadecimal color value which starts with a `#` followed by 3 or 6 numerals.
                The default value was chosen as it is distinguishable for most color-blind people.
            active: If set to `False` the region is marked as 'deleted'

        Returns:
            Region with added polygon

        Examples:
            ```python
            region = region.add_polygon(
                points=[(0.1, 0.1), (0.2, 0.2), (0.3, 0.3)],
            )
            ```

            ```python
            # with custom display values
            region = region.add_polygon(
                points=[(0.1, 0.1), (0.2, 0.2), (0.3, 0.3)],
                line_width=3,
                color="#32a873",
            )
            ```
        """
        geom_points = [GeometryPoint(val[0], val[1], self.res_id) for val in points]
        self.geometry = Polygon(
            points=geom_points, line_width=line_width, color=color, active=active, resource_id=self.res_id
        )
        return self

    def add_circle(
        self,
        center: tuple[float, float],
        radius: tuple[float, float],
        line_width: float = 2,
        color: str = "#5b24bf",
        active: bool = True,
    ) -> RegionResource:
        """
        Add a circle shape to the region.

        [For a visual example see the XML documentation](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#geometry)

        **Please note that this cannot currently be displayed in the dsp-app.**

        Args:
            center: center of the circle, represented as two numbers between 0 and 1 in the format (x, y)
            radius: radius of the circle, represented as a 2-dimensional vector,
                i.e. two numbers between 0 and 1 in the format (x, y)
            line_width: A number in pixels between 1 - 5
            color: A hexadecimal color value which starts with a `#` followed by 3 or 6 numerals.
                The default value was chosen as it is distinguishable for most color-blind people.
            active: If set to `False` the region is marked as 'deleted'

        Returns:
            Region with added circle

        Examples:
            ```python
            region = region.add_circle(
                center=(0.1, 0.1),
                radius=(0.2, 0.2),
            )
            ```

            ```python
            # with custom display values
            region = region.add_circle(
                center=(0.1, 0.1),
                radius=(0.2, 0.2),
                line_width=3,
                color="#32a873",
            )
            ```
        """
        self.geometry = Circle(
            center=GeometryPoint(center[0], center[1], self.res_id),
            radius=Vector(radius[0], radius[1], self.res_id),
            line_width=line_width,
            color=color,
            active=active,
            resource_id=self.res_id,
        )
        return self

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

        Args:
            comment: text

        Returns:
            The original region, with the added comment

        Examples:
            ```python
            region = region.add_comment("comment text")
            ```
        """
        self.comments.append(comment)
        return self

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

        Args:
            comments: list of texts

        Returns:
            The original region, with the added comments

        Examples:
            ```python
            region = region.add_comment_multiple(["comment 1", "comment 2"])
            ```
        """
        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 region unchanged.

        Args:
            comment: text or empty value

        Returns:
            The original region, with the added comment

        Examples:
            ```python
            region = region.add_comment_optional("comment text")
            ```

            ```python
            region = region.add_comment_optional(None)
            ```
        """
        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 region in SALSAH
            iri: Original IRI in SALSAH
            ark: Original ARK in SALSAH

        Raises:
            InputError: if metadata already exists

        Returns:
            The original region, with the added metadata

        Examples:
            ```python
            region = region.add_migration_metadata(
                iri="http://rdfh.ch/4123/DiAmYQzQSzC7cdTo6OJMYA",
                creation_date="1999-12-31T23:59:59.9999999+01:00"
            )
            ```
        """
        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.extend(self._serialise_geometry_shape())
        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 [
            LinkValue(value=self.region_of, prop_name="isRegionOf", resource_id=self.res_id).serialise(),
        ]

    def _serialise_geometry_shape(self) -> list[etree._Element]:
        prop_list: list[etree._Element] = []
        if not self.geometry:
            msg = (
                f"The region resource with the ID '{self.res_id}' does not have a geometry, "
                f"please note that an xmlupload will fail."
            )
            warnings.warn(DspToolsUserWarning(msg))

            return prop_list
        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 = self.geometry.to_json_string()
        geo_prop.append(ele)
        prop_list.append(geo_prop)
        prop_list.append(
            ColorValue(value=self.geometry.color, prop_name="hasColor", resource_id=self.res_id).serialise(),
        )
        return prop_list

create_new

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

Exactly one geometry shape has to be added to the resource with one of the following methods: add_rectangle, add_polygon, add_circle (see documentation below for more information).

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
region_of	str	ID of the image resource that this region refers to (cardinality 1)	required
permissions	Permissions	permissions of this region resource	PROJECT_SPECIFIC_PERMISSIONS

Returns:

Type	Description
RegionResource	A region resource

Examples:

region = xmllib.RegionResource.create_new(
    res_id="ID",
    label="label",
    region_of="image_id",
)

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

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

    Exactly one geometry shape has to be added to the resource with one of the following methods:
    `add_rectangle`, `add_polygon`, `add_circle` (see documentation below for more information).

    [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
        region_of: ID of the image resource that this region refers to (cardinality 1)
        permissions: permissions of this region resource

    Returns:
        A region resource

    Examples:
        ```python
        region = xmllib.RegionResource.create_new(
            res_id="ID",
            label="label",
            region_of="image_id",
        )
        ```
    """
    return RegionResource(
        res_id=res_id,
        label=label,
        region_of=region_of,
        geometry=None,
        permissions=permissions,
    )

add_rectangle

Add a rectangle shape to the region.

For a visual example see the XML documentation

Parameters:

Name	Type	Description	Default
point1	tuple[float, float]	first point of the rectangle represented as two numbers between 0 and 1 in the format (x, y)	required
point2	tuple[float, float]	second point of the rectangle represented as two numbers between 0 and 1 in the format (x, y)	required
line_width	float	A number in pixels between 1 - 5	2
color	str	A hexadecimal color value which starts with a # followed by 3 or 6 numerals. The default value was chosen as it is distinguishable for most color-blind people.	'#5b24bf'
active	bool	If set to False, the region is marked as 'deleted'	True

Returns:

Type	Description
RegionResource	Region with added rectangle

Examples:

region = region.add_rectangle(
    point1=(0.1, 0.1),
    point2=(0.2, 0.2),
)

# with custom display values
region = region.add_rectangle(
    point1=(0.1, 0.1),
    point2=(0.2, 0.2),
    line_width=3,
    color="#32a873",
)

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

def add_rectangle(
    self,
    point1: tuple[float, float],
    point2: tuple[float, float],
    line_width: float = 2,
    color: str = "#5b24bf",
    active: bool = True,
) -> RegionResource:
    """
    Add a rectangle shape to the region.

    [For a visual example see the XML documentation](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#geometry)

    Args:
        point1: first point of the rectangle represented as two numbers between 0 and 1 in the format (x, y)
        point2: second point of the rectangle represented as two numbers between 0 and 1 in the format (x, y)
        line_width: A number in pixels between 1 - 5
        color: A hexadecimal color value which starts with a `#` followed by 3 or 6 numerals.
            The default value was chosen as it is distinguishable for most color-blind people.
        active: If set to `False`, the region is marked as 'deleted'

    Returns:
        Region with added rectangle

    Examples:
        ```python
        region = region.add_rectangle(
            point1=(0.1, 0.1),
            point2=(0.2, 0.2),
        )
        ```

        ```python
        # with custom display values
        region = region.add_rectangle(
            point1=(0.1, 0.1),
            point2=(0.2, 0.2),
            line_width=3,
            color="#32a873",
        )
        ```
    """
    self.geometry = Rectangle(
        point1=GeometryPoint(point1[0], point1[1], self.res_id),
        point2=GeometryPoint(point2[0], point2[1], self.res_id),
        line_width=line_width,
        color=color,
        active=active,
        resource_id=self.res_id,
    )
    return self

add_polygon

Add a polygon shape to the region. A polygon should have at least three points. If you wish to create a rectangle, please use the designated add_rectangle method.

For a visual example see the XML documentation

Please note that this cannot currently be displayed in the dsp-app.

Parameters:

Name	Type	Description	Default
points	list[tuple[float, float]]	list of tuples containing two numbers between 0 and 1 in the format (x, y)	required
line_width	float	A number in pixels between 1 - 5	2
color	str	A hexadecimal color value which starts with a # followed by 3 or 6 numerals. The default value was chosen as it is distinguishable for most color-blind people.	'#5b24bf'
active	bool	If set to False the region is marked as 'deleted'	True

Returns:

Type	Description
RegionResource	Region with added polygon

Examples:

region = region.add_polygon(
    points=[(0.1, 0.1), (0.2, 0.2), (0.3, 0.3)],
)

# with custom display values
region = region.add_polygon(
    points=[(0.1, 0.1), (0.2, 0.2), (0.3, 0.3)],
    line_width=3,
    color="#32a873",
)

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

def add_polygon(
    self,
    points: list[tuple[float, float]],
    line_width: float = 2,
    color: str = "#5b24bf",
    active: bool = True,
) -> RegionResource:
    """
    Add a polygon shape to the region.
    A polygon should have at least three points.
    If you wish to create a rectangle, please use the designated `add_rectangle` method.

    [For a visual example see the XML documentation](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#geometry)

    **Please note that this cannot currently be displayed in the dsp-app.**

    Args:
        points: list of tuples containing two numbers between 0 and 1 in the format (x, y)
        line_width: A number in pixels between 1 - 5
        color: A hexadecimal color value which starts with a `#` followed by 3 or 6 numerals.
            The default value was chosen as it is distinguishable for most color-blind people.
        active: If set to `False` the region is marked as 'deleted'

    Returns:
        Region with added polygon

    Examples:
        ```python
        region = region.add_polygon(
            points=[(0.1, 0.1), (0.2, 0.2), (0.3, 0.3)],
        )
        ```

        ```python
        # with custom display values
        region = region.add_polygon(
            points=[(0.1, 0.1), (0.2, 0.2), (0.3, 0.3)],
            line_width=3,
            color="#32a873",
        )
        ```
    """
    geom_points = [GeometryPoint(val[0], val[1], self.res_id) for val in points]
    self.geometry = Polygon(
        points=geom_points, line_width=line_width, color=color, active=active, resource_id=self.res_id
    )
    return self

add_circle

Add a circle shape to the region.

For a visual example see the XML documentation

Please note that this cannot currently be displayed in the dsp-app.

Parameters:

Name	Type	Description	Default
center	tuple[float, float]	center of the circle, represented as two numbers between 0 and 1 in the format (x, y)	required
radius	tuple[float, float]	radius of the circle, represented as a 2-dimensional vector, i.e. two numbers between 0 and 1 in the format (x, y)	required
line_width	float	A number in pixels between 1 - 5	2
color	str	A hexadecimal color value which starts with a # followed by 3 or 6 numerals. The default value was chosen as it is distinguishable for most color-blind people.	'#5b24bf'
active	bool	If set to False the region is marked as 'deleted'	True

Returns:

Type	Description
RegionResource	Region with added circle

Examples:

region = region.add_circle(
    center=(0.1, 0.1),
    radius=(0.2, 0.2),
)

# with custom display values
region = region.add_circle(
    center=(0.1, 0.1),
    radius=(0.2, 0.2),
    line_width=3,
    color="#32a873",
)

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

def add_circle(
    self,
    center: tuple[float, float],
    radius: tuple[float, float],
    line_width: float = 2,
    color: str = "#5b24bf",
    active: bool = True,
) -> RegionResource:
    """
    Add a circle shape to the region.

    [For a visual example see the XML documentation](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#geometry)

    **Please note that this cannot currently be displayed in the dsp-app.**

    Args:
        center: center of the circle, represented as two numbers between 0 and 1 in the format (x, y)
        radius: radius of the circle, represented as a 2-dimensional vector,
            i.e. two numbers between 0 and 1 in the format (x, y)
        line_width: A number in pixels between 1 - 5
        color: A hexadecimal color value which starts with a `#` followed by 3 or 6 numerals.
            The default value was chosen as it is distinguishable for most color-blind people.
        active: If set to `False` the region is marked as 'deleted'

    Returns:
        Region with added circle

    Examples:
        ```python
        region = region.add_circle(
            center=(0.1, 0.1),
            radius=(0.2, 0.2),
        )
        ```

        ```python
        # with custom display values
        region = region.add_circle(
            center=(0.1, 0.1),
            radius=(0.2, 0.2),
            line_width=3,
            color="#32a873",
        )
        ```
    """
    self.geometry = Circle(
        center=GeometryPoint(center[0], center[1], self.res_id),
        radius=Vector(radius[0], radius[1], self.res_id),
        line_width=line_width,
        color=color,
        active=active,
        resource_id=self.res_id,
    )
    return self

add_comment

Add a comment to the region

Parameters:

Name	Type	Description	Default
comment	str	text	required

Returns:

Type	Description
RegionResource	The original region, with the added comment

Examples:

region = region.add_comment("comment text")

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 region

    Args:
        comment: text

    Returns:
        The original region, with the added comment

    Examples:
        ```python
        region = region.add_comment("comment text")
        ```
    """
    self.comments.append(comment)
    return self

add_comment_multiple

Add several comments to the region

Parameters:

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

Returns:

Type	Description
RegionResource	The original region, with the added comments

Examples:

region = region.add_comment_multiple(["comment 1", "comment 2"])

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 region

    Args:
        comments: list of texts

    Returns:
        The original region, with the added comments

    Examples:
        ```python
        region = region.add_comment_multiple(["comment 1", "comment 2"])
        ```
    """
    self.comments.extend(comments)
    return self

add_comment_optional

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

Parameters:

Name	Type	Description	Default
comment	Any	text or empty value	required

Returns:

Type	Description
RegionResource	The original region, with the added comment

Examples:

region = region.add_comment_optional("comment text")

region = region.add_comment_optional(None)

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 region unchanged.

    Args:
        comment: text or empty value

    Returns:
        The original region, with the added comment

    Examples:
        ```python
        region = region.add_comment_optional("comment text")
        ```

        ```python
        region = region.add_comment_optional(None)
        ```
    """
    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 region 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 region, with the added metadata

Examples:

region = region.add_migration_metadata(
    iri="http://rdfh.ch/4123/DiAmYQzQSzC7cdTo6OJMYA",
    creation_date="1999-12-31T23:59:59.9999999+01:00"
)

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 region in SALSAH
        iri: Original IRI in SALSAH
        ark: Original ARK in SALSAH

    Raises:
        InputError: if metadata already exists

    Returns:
        The original region, with the added metadata

    Examples:
        ```python
        region = region.add_migration_metadata(
            iri="http://rdfh.ch/4123/DiAmYQzQSzC7cdTo6OJMYA",
            creation_date="1999-12-31T23:59:59.9999999+01:00"
        )
        ```
    """
    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