Add filtering and geometry functionalities to ElementCollection

- Introduced `and_` method for combining collections with AND logic.
- Added `between` method for numeric comparisons.
- Enhanced `equals` method to support also numbers.
- Implemented `getGeometry` function for height filtering.
- Updated documentation for clarity on method usage and parameters.
- Added example usage in examples.py.

Author: runxel

examples/examples.py

@@ -27,6 +27,13 @@
 )
 print(col_elements)
 
+wanted = (
+	elements.filterBy(Filter.PROPERTY)
+	.property("Prop Group Name", "Prop Name")
+	.between(1.0, 2.5)
+)
+print(wanted)
+
 # perisso supports slicing, too
 print(col_elements[0])
 
@@ -37,6 +44,8 @@
 print(structural)
 
 # additional functionalities:
-perisso().filterBy(Filter.PROPERTY).property("Prop Group Name", "Prop Name").equals("test").highlight()
+perisso().filterBy(Filter.PROPERTY).property("Prop Group Name", "Prop Name").equals(
+	"test"
+).highlight()
 sleep(5)
 clearhighlight()

src/perisso/collection.py

@@ -1,6 +1,6 @@
 from archicad import Types as act
 from .enums import ElType, Filter
-from .utils import getPropValues, getDetails, rtc, acu, _pprint  # noqa: F401
+from .utils import getPropValues, getDetails, getGeometry, rtc, acu, _pprint  # noqa: F401
 
 
 class ElementCollection:
@@ -35,6 +35,8 @@ def __init__(self, elements, *, _field=None, _propGUID: str = None):
 			Filter.PROPERTY: lambda elements: getPropValues(
 				propGUID=self._propGUID, elements=elements
 			),
+			# geometry
+			Filter.HEIGHT: lambda elements: getGeometry(Filter.HEIGHT, elements),
 		}
 
 	def filterBy(self, field: Filter):
@@ -46,7 +48,13 @@ def filterBy(self, field: Filter):
 		return self
 
 	def property(self, group: str, name: str):
-		"""When filtering to a property all elements that do not have the property available are discarded."""
+		"""Must follow on a `.filterBy(Filter.PROPERTY)` to specify which Property should be read.
+		Please note: When filtering to a property all elements that do not have the property available are discarded.
+
+		Args:
+			group (`str`): Property group name.
+			name (`str`): Property name.
+		"""
 		if not self._field == Filter.PROPERTY:
 			raise ValueError("`filterBy()` must be set to `Filter.PROPERTY'")
 
@@ -68,6 +76,41 @@ def property(self, group: str, name: str):
 			filtered, _field=Filter.PROPERTY, _propGUID=self._propGUID
 		)
 
+	def and_(self, other_collection_or_callable):
+		"""Combine with another ElementCollection using AND logic (intersection).
+
+		Args:
+			other_collection_or_callable: Either an ElementCollection or a callable
+				that takes this collection and returns an ElementCollection
+
+		Returns:
+			ElementCollection: New collection containing only elements present in both collections
+		"""
+		if callable(other_collection_or_callable):
+			other_collection = other_collection_or_callable(
+				ElementCollection(self.elements)
+			)
+		elif isinstance(other_collection_or_callable, ElementCollection):
+			other_collection = other_collection_or_callable
+		else:
+			raise TypeError(
+				"Argument must be an ElementCollection or callable returning one"
+			)
+
+		# Get GUIDs from the other collection
+		other_guids = {
+			element["elementId"]["guid"] for element in other_collection.elements
+		}
+
+		# Keep only elements that exist in both collections
+		intersection_elements = [
+			element
+			for element in self.elements
+			if element["elementId"]["guid"] in other_guids
+		]
+
+		return ElementCollection(intersection_elements)
+
 	# region // string comparisons
 	def startsWith(self, value: str | ElType, casesensitive: bool = True):
 		if not self._field:
@@ -151,31 +194,150 @@ def contains(self, value: str | ElType, casesensitive: bool = True):
 
 		return ElementCollection(filtered)
 
-	def equals(self, value: str | ElType, casesensitive: bool = True):
+	def equals(self, value: str | int | float | ElType, casesensitive: bool = True):
+		"""Keep only the elements whose value match the input.
+		Args:
+			value (`str` | `int`| `float`| `ElType`): Value to check against.
+			casesensitive (`bool`): Determines if the check should be perforemed case-sensitive.
+
+		Returns:
+			`ElementCollection`: Returns a new ElementCollection.
+		"""
 		if not self._field:
 			raise ValueError("Must call filterBy() first")
 
 		if isinstance(value, ElType):
 			# get 'value' from enum
 			value = value.value
 
-		if not casesensitive:
-			value = value.casefold()
+		handler = self._pattern_handlers.get(self._field)
+		if handler:
+			ret_values = handler(self.elements)
+			filtered = []
+			for i, item in enumerate(ret_values):
+				if item["ok"]:  # exclude errors
+					if isinstance(value, (int, float)):
+						try:
+							item_value = float(item["value"])
+							if item_value == value:
+								filtered.append(self.elements[i])
+						except (ValueError, TypeError):
+							# Skip non-numeric values
+							continue
+					else:
+						# String comparison
+						if not casesensitive:
+							value = value.casefold()
+
+						item_str = (
+							str(item["value"]).casefold()
+							if not casesensitive
+							else str(item["value"])
+						)
+						if value == item_str:
+							filtered.append(self.elements[i])
+
+		return ElementCollection(filtered)
+
+	# endregion //
+
+	# region // numeric comparisons
+	def lessThan(self, value: int | float, inclusive: bool = False):
+		"""Keep only elements whose numeric value is less than the input.
+		Args:
+			value (`int` | `float`): Numeric value to compare against.
+			inclusive (`bool`): If True, uses <= instead of <.
+
+		Returns:
+			`ElementCollection`: Returns a new ElementCollection.
+		"""
+		if not self._field:
+			raise ValueError("Must call filterBy() first")
 
 		handler = self._pattern_handlers.get(self._field)
 		if handler:
 			ret_values = handler(self.elements)
-			filtered = [
-				self.elements[i]
-				for i, item in enumerate(ret_values)
-				if item["ok"]  # exclude errors
-				and value
-				== (
-					str(item["value"]).casefold()
-					if not casesensitive
-					else str(item["value"])
-				)
-			]
+			filtered = []
+			for i, item in enumerate(ret_values):
+				if item["ok"]:  # exclude errors
+					try:
+						item_value = float(item["value"])
+						if inclusive:
+							if item_value <= value:
+								filtered.append(self.elements[i])
+						else:
+							if item_value < value:
+								filtered.append(self.elements[i])
+					except (ValueError, TypeError):
+						# Skip non-numeric values
+						continue
+
+		return ElementCollection(filtered)
+
+	def greaterThan(self, value: int | float, inclusive: bool = False):
+		"""Keep only elements whose numeric value is greater than the input.
+		Args:
+			value (`int` | `float`): Numeric value to compare against.
+			inclusive (`bool`): If True, uses >= instead of >.
+
+		Returns:
+			`ElementCollection`: Returns a new ElementCollection.
+		"""
+		if not self._field:
+			raise ValueError("Must call filterBy() first")
+
+		handler = self._pattern_handlers.get(self._field)
+		if handler:
+			ret_values = handler(self.elements)
+			filtered = []
+			for i, item in enumerate(ret_values):
+				if item["ok"]:  # exclude errors
+					try:
+						item_value = float(item["value"])
+						if inclusive:
+							if item_value >= value:
+								filtered.append(self.elements[i])
+						else:
+							if item_value > value:
+								filtered.append(self.elements[i])
+					except (ValueError, TypeError):
+						# Skip non-numeric values
+						continue
+
+		return ElementCollection(filtered)
+
+	def between(
+		self, min_value: int | float, max_value: int | float, inclusive: bool = True
+	):
+		"""Keep only elements whose numeric value is between min and max values.
+		Args:
+			min_value (`int` | `float`): Minimum value (lower bound).
+			max_value (`int` | `float`): Maximum value (upper bound).
+			inclusive (`bool`): If True, includes boundary values.
+
+		Returns:
+			`ElementCollection`: Returns a new ElementCollection.
+		"""
+		if not self._field:
+			raise ValueError("Must call filterBy() first")
+
+		handler = self._pattern_handlers.get(self._field)
+		if handler:
+			ret_values = handler(self.elements)
+			filtered = []
+			for i, item in enumerate(ret_values):
+				if item["ok"]:  # exclude errors
+					try:
+						item_value = float(item["value"])
+						if inclusive:
+							if min_value <= item_value <= max_value:
+								filtered.append(self.elements[i])
+						else:
+							if min_value < item_value < max_value:
+								filtered.append(self.elements[i])
+					except (ValueError, TypeError):
+						# Skip non-numeric values
+						continue
 
 		return ElementCollection(filtered)
 
@@ -208,6 +370,23 @@ def highlight(
 		noncolor: list[int] = [164, 166, 165, 128],
 		wireframe=True,
 	):
+		"""Highlight elements in the collection with specified colors.
+		Args:
+			color (`list[int]`, optional): RGBA color values for highlighted elements.
+				Must be a list of exactly 4 integers.
+			noncolor (`list[int]`, optional): RGBA color values for non-highlighted elements.
+				Must be a list of exactly 4 integers.
+			wireframe (`bool`, optional): Whether to display elements in wireframe mode in 3D.
+				Defaults to True.
+		Returns:
+			self: Returns the collection instance for method chaining.
+		Raises:
+			ValueError: If color or noncolor parameters are not lists of exactly 4 integers,
+				or if any color values are not integers.
+		Example:
+			>>> collection.highlight(color=[255, 0, 0, 255], wireframe=False)
+			>>> collection.highlight(noncolor=[128, 128, 128, 100])
+		"""
 		# Validate color parameter
 		if not isinstance(color, list) or len(color) != 4:
 			raise ValueError("Color must be a list of exactly 4 integers")

src/perisso/enums.py

@@ -95,4 +95,4 @@ class Filter(Enum):
 
 	# geometry
 	# LENGTH = "length"
-	# HEIGHT = "heigth"
+	HEIGHT = "height"

src/perisso/utils.py

@@ -1,7 +1,7 @@
 import json
 from archicad import ACConnection
 from archicad.releases import Commands, Types, Utilities
-from .enums import Filter
+from .enums import Filter, ElType
 
 # Connection setup
 conn = ACConnection.connect()
@@ -15,7 +15,12 @@
 
 def rtc(command: str, *args):
 	"""Run a Tapir Command \n
-	Uses the official `archicad` package.
+	Uses the official `archicad` package for that.
+
+	Args:
+		command (`str`): The name of the tapir command to be run.
+		*args (`dict`): Usually a dict with the additional parameters.
+			Could look like this: `{"elements": perisso().get()}`
 	"""
 	if args:
 		return acc.ExecuteAddOnCommand(
@@ -83,10 +88,40 @@ def _getPropValues(*, builtin: str = None, propGUID: str = None, elements: dict
 	return ret_values
 
 
-def getDetails(type_: Filter, elements: dict) -> list:
+def getDetails(filter: Filter, elements: dict) -> list:
 	json_ = rtc("GetDetailsOfElements", {"elements": elements})["detailsOfElements"]
 	ret_values = []
-	if type_ == Filter.ELEMENT_TYPE:
+	if filter == Filter.ELEMENT_TYPE:
 		# ElementType can never be error
 		ret_values = [{"ok": True, "value": i["type"]} for i in json_]
+	else:
+		raise NotImplementedError
+	return ret_values
+
+
+def getGeometry(filter: Filter, elements: dict) -> list:
+	ret_values = []
+	elem_types = getDetails(filter=Filter.ELEMENT_TYPE, elements=elements)
+	if filter == Filter.HEIGHT:
+		for i, item in enumerate(elements):
+			if elem_types[i]["value"] == ElType.MORPH.value:
+				ret_values.append({"ok": True, "value": _getBBoxSize([item])[0]["z"]})
+			else:
+				ret_values.append({"ok": False, "error": "not implemented"})
+	else:
+		raise NotImplementedError
+	return ret_values
+
+
+def _getBBoxSize(elements: dict) -> list:
+	"""Gets the size of the fitted Bounding Box of the elements."""
+	ret_values = []
+	bboxes_raw = rtc("Get3DBoundingBoxes", {"elements": elements})
+	for i, item in enumerate(bboxes_raw["boundingBoxes3D"]):
+		dimensions = {
+			"x": item["boundingBox3D"]["xMax"] - item["boundingBox3D"]["xMin"],
+			"y": item["boundingBox3D"]["yMax"] - item["boundingBox3D"]["yMin"],
+			"z": item["boundingBox3D"]["zMax"] - item["boundingBox3D"]["zMin"],
+		}
+		ret_values.append(dimensions)
 	return ret_values