pooltool.physics.resolve.ball_cushion.unrealistic ================================================= .. py:module:: pooltool.physics.resolve.ball_cushion.unrealistic An unrealistic ball-cushion model --------------------------------- Overview -------- .. list-table:: Classes :header-rows: 0 :widths: auto :class: summarytable * - :py:obj:`Ball ` - A billiards ball * - :py:obj:`CircularCushionSegment ` - A circular cushion segment defined by a circle center and radius * - :py:obj:`LinearCushionSegment ` - A linear cushion segment defined by the line between points p1 and p2 * - :py:obj:`CoreBallCCushionCollision ` - Operations used by every ball-linear cushion collision resolver * - :py:obj:`CoreBallLCushionCollision ` - Operations used by every ball-linear cushion collision resolver * - :py:obj:`BallCCushionModel ` - An Enum for different ball-circular cushion collision models * - :py:obj:`BallLCushionModel ` - An Enum for different ball-linear cushion collision models * - :py:obj:`UnrealisticLinear ` - Operations used by every ball-linear cushion collision resolver * - :py:obj:`UnrealisticCircular ` - Operations used by every ball-linear cushion collision resolver Classes ------- .. autoclass:: Ball .. py:property:: xyz The displacement (from origin) vector of the ball. A shortcut for ``self.state.rvw[0]``. .. py:property:: vel The velocity vector of the ball. A shortcut for ``self.state.rvw[1]``. .. py:property:: avel The angular velocity vector of the ball. A shortcut for ``self.state.rvw[2]``. .. rubric:: Methods: .. py:method:: set_ballset(ballset: pooltool.objects.ball.sets.BallSet) -> None Update the ballset :raises ValueError: If the ball ID doesn't match to a model name of the ballset. .. seealso:: - See :mod:`pooltool.objects.ball.sets` for details about ball sets. - See :meth:`pooltool.system.datatypes.System.set_ballset` for setting the ballset for all the balls in a system. .. py:method:: copy(drop_history: bool = False) -> Ball Create a copy :param drop_history: If True, the returned copy :attr:`history` and :attr:`history_cts` attributes are both set to empty :class:`BallHistory` objects. .. py:method:: create(id: str, *, xy: Optional[Sequence[float]] = None, ballset: Optional[pooltool.objects.ball.sets.BallSet] = None, **kwargs) -> Ball :staticmethod: Create a ball using keyword arguments. This constructor flattens the tunable parameter space, allowing one to construct a ``Ball`` without directly instancing objects like like :class:`pooltool.objects.balls.params.BallParams` and :class:`BallState`. :param xy: The x and y coordinates of the ball position. :param ballset: A ballset. :param \*\*kwargs: Arguments accepted by :class:`pooltool.objects.balls.params.BallParams` .. autoclass:: CircularCushionSegment .. py:property:: height :type: float The height of the cushion .. cached_property_note:: .. py:property:: a :type: float The x-coordinate of the cushion's center .. cached_property_note:: .. py:property:: b :type: float The y-coordinate of the cushion's center .. cached_property_note:: .. rubric:: Methods: .. py:method:: get_normal(rvw: numpy.typing.NDArray[numpy.float64]) -> numpy.typing.NDArray[numpy.float64] Calculates the normal vector for a ball contacting the cushion Assumes that the ball is in fact in contact with the cushion. :param rvw: The kinematic state vectors of the contacting ball (see :param :attr:`pooltool.objects.ball.datatypes.BallState.rvw`).: :returns: The normal vector, with the z-component set to 0. :rtype: NDArray[np.float64] .. py:method:: copy() -> CircularCushionSegment Create a copy .. autoclass:: LinearCushionSegment .. py:property:: height :type: float The height of the cushion .. cached_property_note:: .. py:property:: lx :type: float The x-coefficient (:math:`l_x`) of the cushion's 2D general form line equation .. cached_property_note:: The cushion's general form line equation in the :math:`XY` plane (*i.e.* dismissing the z-component) is .. math:: l_x x + l_y y + l_0 = 0 where .. math:: \begin{align*} l_x &= -\frac{p_{2y} - p_{1y}}{p_{2x} - p_{1x}} \\ l_y &= 1 \\ l_0 &= \frac{p_{2y} - p_{1y}}{p_{2x} - p_{1x}} p_{1x} - p_{1y} \\ \end{align*} .. py:property:: ly :type: float The x-coefficient (:math:`l_y`) of the cushion's 2D general form line equation See :meth:`lx` for definition. .. cached_property_note:: .. py:property:: l0 :type: float The constant term (:math:`l_0`) of the cushion's 2D general form line equation See :meth:`lx` for definition. .. cached_property_note:: .. py:property:: normal :type: numpy.typing.NDArray[numpy.float64] The line's normal vector, with the z-component set to 0. .. warning:: The returned normal vector is arbitrarily directed, meaning it may point away from the table surface, rather than towards it. This nonideality is properly handled in downstream simulation logic, however if you're using this method for custom purposes, you may want to reverse the direction of this vector by negating it. .. rubric:: Methods: .. py:method:: get_normal(rvw: numpy.typing.NDArray[numpy.float64]) -> numpy.typing.NDArray[numpy.float64] Calculates the normal vector .. warning:: The returned normal vector is arbitrarily directed, meaning it may point away from the table surface, rather than towards it. This nonideality is properly handled in downstream simulation logic, however if you're using this method for custom purposes, you may want to reverse the direction of this vector by negating it. :param rvw: The kinematic state vectors of the contacting balls. See ``rvw`` parameter of :class:`pooltool.objects.ball.datatypes.BallState`. :returns: The line's normal vector, with the z-component set to 0. :rtype: NDArray[np.float64] .. note:: - This method only exists for call signature parity with :meth:`CircularCushionSegment.get_normal`. Consider using :meth:`normal` instead. .. py:method:: copy() -> LinearCushionSegment Create a copy .. autoclass:: CoreBallCCushionCollision Bases: :py:obj:`abc.ABC` .. rubric:: Methods: .. py:method:: make_kiss(ball: pooltool.objects.ball.datatypes.Ball, cushion: pooltool.objects.table.components.CircularCushionSegment) -> pooltool.objects.ball.datatypes.Ball Translate the ball so it (almost) touches the circular cushion segment This makes a correction such that if the ball is not a distance R from the cushion, the ball is moved along the normal such that it is. To avoid downstream float precision round-off error, a small epsilon of additional distance (constants.EPS_SPACE) is put between them, ensuring the cushion and ball are separated post-resolution. .. autoclass:: CoreBallLCushionCollision Bases: :py:obj:`abc.ABC` .. rubric:: Methods: .. py:method:: make_kiss(ball: pooltool.objects.ball.datatypes.Ball, cushion: pooltool.objects.table.components.LinearCushionSegment) -> pooltool.objects.ball.datatypes.Ball Translate the ball so it (almost) touches the linear cushion segment This makes a correction such that if the ball is not a distance R from the cushion, the ball is moved along the normal such that it is. To avoid downstream float precision round-off error, a small epsilon of additional distance (constants.EPS_SPACE) is put between them, ensuring the cushion and ball are separated post-resolution. .. autoclass:: BallCCushionModel Bases: :py:obj:`pooltool.utils.strenum.StrEnum` .. autoclass:: BallLCushionModel Bases: :py:obj:`pooltool.utils.strenum.StrEnum` .. autoclass:: UnrealisticLinear Bases: :py:obj:`pooltool.physics.resolve.ball_cushion.core.CoreBallLCushionCollision` .. autoclass:: UnrealisticCircular Bases: :py:obj:`pooltool.physics.resolve.ball_cushion.core.CoreBallCCushionCollision`