Scene API

class Scene:
    """Manages the scene graph for a protein structure visualization.

    The Scene holds the core protein structure data and a hierarchical
    tree of SceneElements (nodes), including SceneGroups.
    It provides methods to build and manipulate this tree, and to query
    elements based on residue information.
    """

    def __init__(self, structure: Structure):
        """Initializes the Scene with a core Structure object.

        Args:
            structure: The core biological structure data.
        """
        if not isinstance(structure, Structure):
            raise TypeError("Scene must be initialized with a Structure object.")

        self._structure: Structure = structure
        # List of top-level nodes (elements with no parent)
        # The order here determines the base rendering order of top-level items.
        self._nodes: List[BaseSceneElement] = []
        # For quick lookups by ID
        self._element_registry: Dict[str, BaseSceneElement] = {}
        # Create the coordinate resolver instance
        self._resolver: Optional[CoordinateResolver] = None  # Initialize as None

    @property
    def structure(self) -> Structure:
        """Get the core Structure object associated with this scene."""
        return self._structure

    @property
    def top_level_nodes(self) -> List[BaseSceneElement]:
        """Get the list of top-level nodes in the scene graph."""
        return self._nodes

    def get_element_by_id(self, id: str) -> Optional[BaseSceneElement]:
        """Retrieve a scene element by its unique ID.

        Args:
            id: The ID of the element to find.

        Returns:
            The found BaseSceneElement or None if no element has that ID.
        """
        return self._element_registry.get(id)

    def _register_element(self, element: BaseSceneElement) -> None:
        """Internal method to add an element to the ID registry."""
        if element.id in self._element_registry:
            # Raise specific error for duplicate IDs
            raise DuplicateElementError(
                f"Element with ID '{element.id}' already exists in the registry."
            )
        self._element_registry[element.id] = element

    def _unregister_element(self, element: BaseSceneElement) -> None:
        """Internal method to remove an element from the ID registry."""
        if element.id in self._element_registry:
            del self._element_registry[element.id]
        # Invalidate resolver cache if element affecting it is removed
        self._resolver = None

    def add_element(
        self, element: BaseSceneElement, parent_id: Optional[str] = None
    ) -> None:
        """Adds a SceneElement to the scene graph.

        If parent_id is provided, the element is added as a child of the
        specified parent group. Otherwise, it's added as a top-level node.

        Args:
            element: The SceneElement to add.
            parent_id: The ID of the parent SceneGroup, or None for top-level.

        Raises:
            ValueError: If parent_id is specified but not found, or if the
                        target parent is not a SceneGroup, or if the element ID
                        already exists.
            TypeError: If the element is not a BaseSceneElement.
        """
        if not isinstance(element, BaseSceneElement):
            # Raise specific type error
            raise ElementTypeError(
                f"Object to add is not a BaseSceneElement subclass (got {type(element).__name__})."
            )

        # Check for existing element using ID registry (more reliable)
        if element.id in self._element_registry:
            raise DuplicateElementError(
                f"Element with ID '{element.id}' already exists in the registry."
            )

        # Check if element object seems already attached (should have parent=None)
        # This prevents adding the same *object* instance twice if somehow unregistered but still linked
        if element.parent is not None:
            raise InvalidSceneOperationError(
                f"Element '{element.id}' already has a parent ('{element.parent.id}') and cannot be added directly."
            )

        # Check if it's already a top-level node (should not happen if parent is None check passes, but belt-and-suspenders)
        if element in self._nodes:
            raise InvalidSceneOperationError(
                f"Element '{element.id}' is already a top-level node."
            )

        self._register_element(element)  # Register first

        parent: Optional[SceneGroup] = None
        if parent_id is not None:
            potential_parent = self.get_element_by_id(parent_id)
            if potential_parent is None:
                self._unregister_element(element)  # Rollback
                # Raise specific error for parent not found
                raise ParentNotFoundError(
                    f"Parent group with ID '{parent_id}' not found."
                )
            if not isinstance(potential_parent, SceneGroup):
                self._unregister_element(element)  # Rollback
                # Raise specific type error for parent
                raise ElementTypeError(
                    f"Specified parent '{parent_id}' is not a SceneGroup (got {type(potential_parent).__name__})."
                )
            parent = potential_parent

        try:
            if parent:
                # Let add_child raise its specific errors (e.g., ValueError for circular)
                parent.add_child(element)
            else:
                element._set_parent(None)
                self._nodes.append(element)
        except (ValueError, TypeError, SceneError) as e:
            # Catch potential errors from add_child or _set_parent
            self._unregister_element(
                element
            )  # Rollback registration (also invalidates resolver)
            if parent is None and element in self._nodes:
                self._nodes.remove(element)  # Rollback adding to top-level
            # Re-raise the original specific error, don't wrap
            raise e
        # Invalidate resolver cache if element affecting it is added
        self._resolver = None

    def remove_element(self, element_id: str) -> None:
        """Removes a SceneElement and its descendants from the scene graph by ID.

        Args:
            element_id: The ID of the SceneElement to remove.

        Raises:
            ValueError: If the element with the given ID is not found in the scene.
        """
        element = self.get_element_by_id(element_id)
        if element is None:
            # Raise specific error
            raise ElementNotFoundError(f"Element with ID '{element_id}' not found.")

        # --- Collect nodes to remove --- (No change needed here)
        nodes_to_unregister: List[BaseSceneElement] = []
        nodes_to_process: List[BaseSceneElement] = [element]

        while nodes_to_process:
            node = nodes_to_process.pop(0)
            # Check if already unregistered (in case of complex graph manipulations, though ideally not needed)
            if node.id not in self._element_registry:
                continue

            nodes_to_unregister.append(node)
            if isinstance(node, SceneGroup):
                # Add children to process queue (create copy for safe iteration)
                nodes_to_process.extend(list(node.children))

        for node in nodes_to_unregister:
            self._unregister_element(node)

        # --- Detach the root element --- #
        parent = element.parent
        element_was_top_level = element in self._nodes

        if parent:
            if parent.id in self._element_registry and isinstance(parent, SceneGroup):
                try:
                    parent.remove_child(element)
                except ValueError:
                    # This *shouldn't* happen if graph is consistent. Treat as inconsistency.
                    # Log it, but also raise a specific error.
                    element._set_parent(None)
                    # Raise inconsistency error instead of just warning
                    raise SceneGraphInconsistencyError(
                        f"SceneGraph Inconsistency: Element '{element.id}' not found in supposed parent '{parent.id}' children list during removal."
                    )
            else:
                # Parent reference exists but parent is invalid/unregistered.
                element._set_parent(None)
                # This is also an inconsistency
                raise SceneGraphInconsistencyError(
                    f"SceneGraph Inconsistency: Parent '{parent.id if parent else 'None'}' of element '{element.id}' is invalid or unregistered during removal."
                )

        elif element_was_top_level:
            # If it was supposed to be top-level, remove it
            self._nodes.remove(element)
            element._set_parent(None)
        else:
            # Element was registered, had no parent, but wasn't in top-level nodes.
            # This indicates an inconsistency.
            element._set_parent(None)
            raise SceneGraphInconsistencyError(
                f"SceneGraph Inconsistency: Element '{element.id}' was registered but not found in the scene graph structure (neither parented nor top-level)."
            )
        # Invalidate resolver cache since elements were removed
        self._resolver = None

    def move_element(
        self, element_id: str, new_parent_id: Optional[str] = None
    ) -> None:
        """Moves a SceneElement identified by its ID to a new parent.

        Args:
            element_id: The ID of the SceneElement to move.
            new_parent_id: The ID of the new parent SceneGroup, or None to move
                           to the top level.

        Raises:
            ValueError: If the element or new parent is not found, if the new
                        parent is not a SceneGroup, or if the move would create
                        a circular dependency.
            TypeError: If the target parent is not a SceneGroup.
        """
        element = self.get_element_by_id(element_id)
        if element is None:
            raise ElementNotFoundError(f"Element with ID '{element_id}' not found.")

        current_parent = element.parent
        new_parent: Optional[SceneGroup] = None

        if new_parent_id is not None:
            potential_parent = self.get_element_by_id(new_parent_id)
            if potential_parent is None:
                raise ParentNotFoundError(
                    f"New parent group with ID '{new_parent_id}' not found."
                )
            if not isinstance(potential_parent, SceneGroup):
                raise ElementTypeError(
                    f"Target parent '{new_parent_id}' is not a SceneGroup (got {type(potential_parent).__name__})."
                )
            new_parent = potential_parent

            # Prevent circular dependency
            temp_check: Optional[BaseSceneElement] = new_parent
            while temp_check is not None:
                if temp_check is element:
                    raise CircularDependencyError(
                        f"Cannot move element '{element_id}' under '{new_parent_id}' - would create circular dependency."
                    )
                temp_check = temp_check.parent

        if current_parent is new_parent:
            return

        # --- Detach Phase --- #
        element_was_in_nodes = element in self._nodes
        try:
            if current_parent:
                current_parent.remove_child(
                    element
                )  # Let SceneGroup handle internal parent update
            elif element_was_in_nodes:
                self._nodes.remove(element)
                element._set_parent(None)
            elif (
                element.parent is None
            ):  # Already detached, potentially inconsistent state
                raise SceneGraphInconsistencyError(
                    f"SceneGraph Inconsistency: Element '{element_id}' was already detached before move operation."
                )
            else:  # Should not be reachable if graph is consistent
                raise SceneGraphInconsistencyError(
                    f"SceneGraph Inconsistency: Element '{element_id}' in inconsistent state during detach phase of move."
                )
        except ValueError as e:
            # If remove_child fails unexpectedly (e.g., element not found when it should be)
            element._set_parent(None)  # Force detachment
            raise SceneGraphInconsistencyError(
                "Scene Graph Inconsistency: "
                + f"Error detaching '{element_id}' from current parent '{current_parent.id if current_parent else 'None'}': {e}"
            ) from e  # Raise inconsistency

        # --- Attach Phase --- #
        try:
            if new_parent:
                new_parent.add_child(
                    element
                )  # Let add_child handle parent update & checks
            else:
                element._set_parent(None)
                self._nodes.append(element)
        except (ValueError, TypeError, SceneError) as e:
            # If attaching fails, attempt rollback (reattach to original parent/location)
            rollback_msg = f"Failed to attach element '{element_id}' to new parent '{new_parent_id}': {e}. Attempting rollback."
            try:
                if current_parent:
                    current_parent.add_child(
                        element
                    )  # Try adding back to original parent
                elif element_was_in_nodes:  # If it was originally top-level
                    element._set_parent(None)
                    self._nodes.append(element)
                # If originally detached, leave it detached
            except Exception as rollback_e:
                # Rollback failed, graph is likely inconsistent
                msg = f"Rollback failed after attach error for element '{element.id}'. Scene graph may be inconsistent. Rollback error: {rollback_e}"
                raise SceneGraphInconsistencyError(
                    msg
                ) from e  # Raise inconsistency, chaining original error

            raise InvalidSceneOperationError(rollback_msg) from e
        # Invalidate resolver cache since element position changed
        self._resolver = None

    def traverse(self) -> Generator[Tuple[BaseSceneElement, int], None, None]:
        """Performs a depth-first traversal of the scene graph.

        Yields:
            Tuple[BaseSceneElement, int]: A tuple containing the scene element
                                          and its depth in the tree (0 for top-level).
        """
        nodes_to_visit: List[Tuple[BaseSceneElement, int]] = [
            (node, 0) for node in reversed(self._nodes)
        ]
        visited_ids: Set[str] = set()

        while nodes_to_visit:
            element, depth = nodes_to_visit.pop()

            # Check registry in case node was removed during traversal (unlikely but possible)
            if element.id not in self._element_registry or element.id in visited_ids:
                continue
            visited_ids.add(element.id)

            yield element, depth

            if isinstance(element, SceneGroup):
                # Add children to the stack in reverse order to maintain visit order
                # Ensure children are also still registered before adding
                children_to_add = [
                    (child, depth + 1)
                    for child in reversed(element.children)
                    if child.id in self._element_registry
                ]
                nodes_to_visit.extend(children_to_add)

    def get_all_elements(self) -> List[BaseSceneElement]:
        """Returns a flat list of all elements in the scene graph.

        Returns:
            A list containing all BaseSceneElement objects registered in the scene.
        """
        return list(self._element_registry.values())

    def get_sequential_structure_elements(self) -> List[BaseStructureSceneElement]:
        """
        Returns a list of all BaseStructureSceneElement instances in the scene,
        sorted sequentially by chain ID and then by starting residue index.

        Assumes each BaseStructureSceneElement primarily represents a single
        contiguous range for sorting purposes.

        Returns:
            List[BaseStructureSceneElement]: Sorted list of structure elements.
        """
        structure_elements: List[BaseStructureSceneElement] = []
        for element in self._element_registry.values():
            if isinstance(element, BaseStructureSceneElement):
                structure_elements.append(element)

        def sort_key(element: BaseStructureSceneElement) -> Tuple[str, int]:
            primary_chain = "~"  # Use ~ to sort after standard chain IDs
            start_residue = float("inf")  # Sort elements without range last

            if element.residue_range_set and element.residue_range_set.ranges:
                # Use the first range (min start residue) for sorting key
                try:
                    first_range = min(
                        element.residue_range_set.ranges,
                        key=lambda r: (r.chain_id, r.start),
                    )
                    primary_chain = first_range.chain_id
                    start_residue = first_range.start
                except (ValueError, TypeError) as e:
                    logger.warning(
                        f"Could not determine sort key for element {element.id} due to range issue: {e}"
                    )
            else:
                logger.debug(
                    f"Structure element {element.id} has no residue range for sorting."
                )

            # Return a tuple for multi-level sorting
            return (primary_chain, start_residue)

        try:
            structure_elements.sort(key=sort_key)
        except Exception as e:
            logger.error(f"Error sorting structure elements: {e}", exc_info=True)
            # Return unsorted list in case of unexpected sorting error

        return structure_elements

    def __iter__(self) -> Iterator[BaseSceneElement]:
        """Iterate over the top-level nodes of the scene graph."""
        return iter(self._nodes)

    def __len__(self) -> int:
        """Return the total number of elements currently registered in the scene."""
        return len(self._element_registry)

    def __repr__(self) -> str:
        """Provide a string representation of the scene."""
        structure_id = getattr(self.structure, "id", "N/A")  # Safely get structure ID
        return (
            f"<Scene structure_id='{structure_id}' "
            f"top_level_nodes={len(self._nodes)} total_elements={len(self)}>"
        )

    # Lazily create resolver only when needed to avoid issues during Scene init
    @property
    def resolver(self) -> CoordinateResolver:
        """Get the CoordinateResolver instance for this scene."""
        if self._resolver is None:
            # Pass the current element registry
            self._resolver = CoordinateResolver(self._structure, self._element_registry)
        return self._resolver

class BaseSceneElement(ABC, Generic[StyleType]):
    """Abstract base class for all elements within a scene graph.

    This class is generic and requires a specific StyleType that inherits
    from BaseSceneStyle.
    """

    def __init__(
        self,
        id: str,
        style: Optional[StyleType] = None,
        parent: Optional[SceneGroupType] = None,
    ):
        """Initializes a BaseSceneElement.

        Args:
            id: A unique identifier for this scene element.
            style: A style instance for this element.
            parent: The parent SceneGroup in the scene graph, if any.
        """
        if not isinstance(id, str) or not id:
            raise ValueError("SceneElement ID must be a non-empty string.")

        self.id: str = id
        self._style: Optional[StyleType] = style or self.default_style
        self._parent: Optional[SceneGroupType] = parent

    @property
    def parent(self) -> Optional[SceneGroupType]:
        """Get the parent group of this element."""
        return self._parent

    # Keep internal setter for parent relationship management by Scene/SceneGroup
    def _set_parent(self, value: Optional[SceneGroupType]) -> None:
        """Internal method to set the parent group. Should be called by Scene/SceneGroup."""
        # Basic type check, assumes SceneGroup will inherit from BaseSceneElement
        if value is not None and not isinstance(value, BaseSceneElement):
            # A more specific check like isinstance(value, SceneGroup) would be ideal
            # but causes circular dependency issues without careful structuring or protocols.
            # This provides a basic safeguard. We expect SceneGroup to inherit BaseSceneElement.
            raise TypeError(
                "Parent must be a SceneGroup (subclass of BaseSceneElement)."
            )
        self._parent = value

    @property
    @abstractmethod
    def default_style(self) -> StyleType:
        """Provides the default style instance for this element type.

        Subclasses must implement this property.

        Returns:
            An instance of the specific StyleType for this element.
        """
        raise NotImplementedError

    @property
    def style(self) -> StyleType:
        """Get the effective style for this element (instance-specific or default)."""
        return self._style if self._style is not None else self.default_style()

    def update_style(self, new_style: StyleType) -> None:
        """Update the instance-specific style of this element.

        Args:
            new_style: The new style object to apply.
        """
        # Ensure the provided style is compatible
        # Note: isinstance check might be too strict if subclasses of the style are allowed.
        # Adjust check if necessary based on desired style inheritance behavior.
        expected_style_type = self.default_style().__class__
        if not isinstance(new_style, expected_style_type):
            raise TypeError(
                f"Invalid style type. Expected {expected_style_type.__name__}, "
                f"got {type(new_style).__name__}."
            )
        self._style = new_style

    @abstractmethod
    def get_depth(self, structure: Structure) -> Optional[float]:
        """Calculate or retrieve the representative depth for Z-ordering.

        Depth should typically be derived from the pre-projected coordinates
        (column 2) in the provided structure object.
        Lower values are typically closer to the viewer.

        Args:
            structure: The core Structure object containing pre-projected
                       2D + Depth coordinate data.

        Returns:
            A float representing the depth, or None if depth cannot be determined
            or is not applicable (e.g., for groups).
        """
        raise NotImplementedError

    def __repr__(self) -> str:
        """Provide a string representation of the scene element."""
        parent_id = f"'{self._parent.id}'" if self._parent else None
        style_source = "default" if self._style is None else "instance"
        # Safely get range representation, default to 'N/A' if not present
        range_repr = str(getattr(self, "residue_range_set", "N/A"))
        range_str = f" range='{range_repr}'" if range_repr != "N/A" else ""
        target_repr = str(getattr(self, "target", "N/A"))
        target_str = f" target='{target_repr}'" if target_repr != "N/A" else ""

        return (
            f"<{self.__class__.__name__} id='{self.id}'{range_str}{target_str} "
            f"parent={parent_id} style_source={style_source}>"
        )

class BaseSceneStyle(BaseModel):
    """Base class for all scene element style definitions using Pydantic."""

    visibility: bool = Field(
        default=True, description="Whether the element is visible."
    )
    opacity: float = Field(
        default=1.0, ge=0.0, le=1.0, description="Opacity of the element (0.0 to 1.0)."
    )
    # Add other common style attributes here if needed later

    model_config = {"extra": "forbid"}  # Forbid extra fields

class BaseStructureSceneElement(
    BaseSceneElement[StructureStyleType], ABC, Generic[StructureStyleType]
):
    """Abstract base class for scene elements representing structural components.

    Automatically generates an ID based on the subclass type and residue range.
    Requires a concrete style type inheriting from BaseStructureStyle.
    """

    def __init__(
        self,
        residue_range_set: ResidueRangeSet,
        style: Optional[StructureStyleType] = None,
        parent: Optional[SceneGroupType] = None,
    ):
        """Initializes a BaseStructureSceneElement.

        The ID is generated automatically based on the concrete subclass name
        and the provided residue range set.

        Args:
            residue_range_set: The set of residue ranges this element represents.
            style: An optional specific style instance for this element. If None,
                   the default style defined by the subclass's `default_style`
                   property will be used at access time.
            metadata: Optional dictionary for storing arbitrary metadata.
            parent: The parent SceneGroup in the scene graph, if any.
        """
        # Generate the ID *before* calling super().__init__
        # Uses the concrete class's name (e.g., "Helix")
        generated_id = self._generate_id(self.__class__, residue_range_set)

        self.residue_range_set = residue_range_set
        # Pass the potentially None style to the BaseSceneElement constructor.
        # BaseSceneElement's `style` property handles returning the default
        # style if the instance's `_style` attribute is None.
        super().__init__(
            id=generated_id,
            style=style,  # Pass the direct input style (can be None)
            parent=parent,
        )

    @staticmethod
    def _generate_id(cls: type, residue_range_set: ResidueRangeSet) -> str:
        """Generates a unique ID based on class name and residue range set."""
        # Ensure the string representation of the range set is canonical and ID-friendly
        # Replace spaces, commas, and colons to create a valid identifier part.
        # Sorting ranges within the set ensures canonical representation if order matters.
        # Assuming ResidueRangeSet.__str__ provides a consistent, sorted representation.
        range_repr = (
            str(residue_range_set).replace(" ", "").replace(",", "_").replace(":", "-")
        )
        return f"{cls.__name__}-{range_repr}"

    @abstractmethod
    def get_coordinates(self, structure: Structure) -> Optional[np.ndarray]:
        """Retrieve the final 2D + Depth coordinates for rendering this element.

        Implementations should use the element's `residue_range_set` to query
        the provided `structure` object (which is assumed to already contain
        projected 2D + Depth coordinates) and return the relevant slice or
        a simplified representation (e.g., lines for coils) based on these
        pre-projected coordinates.

        Args:
            structure: The core Structure object containing pre-projected
                       2D + Depth coordinate data.

        Returns:
            A NumPy array of 2D + Depth coordinates (shape [N, 3] or similar)
            suitable for rendering (X, Y, Depth).
        """
        raise NotImplementedError

    # Concrete subclasses (Helix, Sheet, etc.) MUST implement default_style
    @property
    @abstractmethod
    def default_style(self) -> StructureStyleType:
        """Provides the default style instance for this specific element type.

        Concrete subclasses (e.g., Helix, Sheet) must implement this property.

        Returns:
            An instance of the specific StyleType (e.g., HelixStyle) for this element.
        """
        raise NotImplementedError

    def get_coordinate_at_residue(
        self, residue: ResidueCoordinate, structure: Structure
    ) -> Optional[np.ndarray]:
        """Retrieves the specific 2D canvas coordinate + Depth corresponding
        to a given residue, derived from the pre-projected coordinates in the
        structure object.

        This default implementation assumes a direct mapping between the residue
        index and the corresponding entry in the main structure.coordinates array.
        Subclasses that implement complex coordinate calculations or simplifications
        in their `get_coordinates` method (e.g., smoothing, interpolation)
        MAY NEED TO OVERRIDE this method to provide the correct mapping to their
        specific rendered representation.

        Args:
            residue: The residue coordinate (chain and index) to find the 2D point for.
            structure: The core Structure object containing pre-projected 2D + Depth data.

        Returns:
            A NumPy array representing the calculated 2D coordinate + Depth (e.g., [X, Y, Depth]),
            or None if the residue is not found or its coordinate cannot be determined.
        """
        try:
            # Check if the residue belongs to the range represented by this element
            if residue not in self.residue_range_set:
                logger.debug(
                    f"Residue {residue} not in range set {self.residue_range_set} for element '{self.id}'"
                )
                return None

            chain = structure[residue.chain_id]

            # Check if the residue index exists in this chain's mapping
            if residue.residue_index not in chain:
                logger.debug(
                    f"Residue {residue} not in chain {chain} for element '{self.id}'"
                )
                return None

            coord_index = chain.coordinate_index(residue.residue_index)
            if not (0 <= coord_index < len(structure.coordinates)):
                struct_id = getattr(structure, "id", "N/A")
                raise CoordinateCalculationError(
                    f"Coordinate index {coord_index} out of bounds for residue {residue} in structure '{struct_id}' (element '{self.id}')."
                )
            return structure.coordinates[coord_index]
        except KeyError:
            logger.debug(
                f"Residue {residue} not in chain {chain} for element '{self.id}'"
            )
            return None
        except (IndexError, AttributeError) as e:
            struct_id = getattr(structure, "id", "N/A")
            raise CoordinateCalculationError(
                f"Error retrieving coordinate for {residue} in structure '{struct_id}' (element '{self.id}'): {e}"
            ) from e

    def get_depth(self, structure: Structure) -> Optional[float]:
        """Calculate the mean depth of this structural element.

        Calculates the mean of the depth values (column 2) of the
        pre-projected coordinates corresponding to the residues in the
        element's residue_range_set.

        Args:
            structure: The core Structure object containing pre-projected
                       2D + Depth coordinate data.

        Returns:
            The mean depth as a float, or None if no coordinates are found.
        """
        # Get coordinates directly from the element's get_coordinates method
        # which handles different element types appropriately
        coords = self.get_coordinates(structure)

        if coords is None or len(coords) == 0:
            return None

        # Extract depth values (Z-coordinate) from the coordinates
        depths = coords[:, 2]

        if len(depths) == 0:
            return None

        return float(np.mean(depths))

    def is_adjacent_to(self, other: "BaseStructureSceneElement") -> bool:
        """Check if this element is adjacent to another element.

        Args:
            other: The other element to check adjacency with.

        Returns:
            True if the elements are adjacent, False otherwise.
        """
        if not isinstance(other, BaseStructureSceneElement):
            raise TypeError(f"Cannot check adjacency with {type(other)}")

        return self.residue_range_set.is_adjacent_to(other.residue_range_set)

    @abstractmethod
    def get_start_connection_point(self, structure: Structure) -> Optional[np.ndarray]:
        """Get the 2D coordinate (X, Y) of the start connection point.

        This is typically the coordinate corresponding to the first residue
        in the element's range, projected onto the 2D canvas.

        Args:
            structure: The core Structure object with pre-projected coordinates.

        Returns:
            A NumPy array [X, Y] or None if not applicable/determinable.
        """
        raise NotImplementedError

    @abstractmethod
    def get_end_connection_point(self, structure: Structure) -> Optional[np.ndarray]:
        """Get the 2D coordinate (X, Y) of the end connection point.

        This is typically the coordinate corresponding to the last residue
        in the element's range, projected onto the 2D canvas.

        Args:
            structure: The core Structure object with pre-projected coordinates.

        Returns:
            A NumPy array [X, Y] or None if not applicable/determinable.
        """
        raise NotImplementedError