Skip to content

Commit

Permalink
api/pupdevices: replace color_map
Browse files Browse the repository at this point in the history 
This reclects the implementation update that changes how
color sensing is performed and interfaced with by the user.
  • Loading branch information
@laurensvalk
laurensvalk committed Oct 8, 2020
1 parent 6671e3d commit d6651fc
Show file tree
Hide file tree
Showing 2 changed files with 58 additions and 52 deletions.
4 changes: 2 additions & 2 deletions doc/api/pupdevices.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -250,7 +250,7 @@ Color and Distance Sensor

.. automethod:: pybricks.pupdevices.ColorDistanceSensor.hsv

.. automethod:: pybricks.pupdevices.ColorDistanceSensor.color_map
.. automethod:: pybricks.pupdevices.ColorDistanceSensor.detectable_colors

.. rubric:: Built-in light

Expand Down Expand Up @@ -380,7 +380,7 @@ Color Sensor

.. automethod:: pybricks.pupdevices.ColorSensor.hsv

.. automethod:: pybricks.pupdevices.ColorSensor.color_map
.. automethod:: pybricks.pupdevices.ColorSensor.detectable_colors

.. rubric:: Built-in lights

Expand Down
106 changes: 56 additions & 50 deletions pybricks/pupdevices.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,10 +81,14 @@ def __init__(self, port):
def color(self):
"""Scans the color of a surface.
You choose which colors are detected using the
:meth:`.detectable_colors` method. By default, it detects
``Color.RED``, ``Color.YELLOW``, ``Color.GREEN``, ``Color.BLUE``,
``Color.WHITE``, or ``None``.
:returns:
Detected color.
:rtype: :class:`Color <.parameters.Color>`, or ``None`` if no color is
detected.
:rtype: :class:`Color <.parameters.Color>`
"""
pass

Expand All @@ -106,38 +110,38 @@ def reflection(self):
"""
pass

def color_map(self, hues, saturation, values):
"""Configures how :meth:`.color` selects a
:class:`Color <.parameters.Color>` based on a :meth:`.hsv` measurement.
def detectable_colors(self, colors):
"""Configures which colors the :meth:`.color` method should detect.
Specify only colors that you wish to detect in your application.
This way, measurements are
rounded to the nearest expected color, and other colors are ignored.
This way, the full-color measurements are rounded to the nearest
desired color, and other colors are ignored. This improves reliability.
If you give no arguments, the current settings will be returned as a
tuple.
If you give no arguments, the currently chosen colors will be returned
as a tuple.
Arguments:
hues (dict): A dictionary that
maps :class:`Color <.parameters.Color>` to hues. When the
saturation is high, :meth:`.color` will return one of these
colors, whichever has the nearest hue.
saturation (:ref:`percentage`): Minimum saturation of a proper
color.
values (:ref:`percentage`): A dictionary that
maps ``Color.WHITE``, ``Color.GRAY``, ``Color.BLACK`` and
``None`` to brightness values. When the saturation is
low, :meth:`.color` will return one of these colors, whichever
has the nearest value.
colors (list): List of :class:`Color <.parameters.Color>` objects:
the colors that you want to detect. You can pick
standard colors such as ``Color.MAGENTA``, or provide your own
colors like
``Color(h=348, s=96, v=40, name='MY_MAGENTA_BRICK')`` for even
better results. You measure your own colors with the
:meth:`.hsv` method.
"""
pass

def hsv(self):
"""Scans the hue, saturation and brightness value of a surface.
"""Scans the color of a surface.
:returns: Tuple with the hue, saturation, and value
(brightness) of the color.
:rtype: (:ref:`hue`, :ref:`percentage`, :ref:`percentage`)
This method is similar to :meth:`.color`, but it gives the full range
of hue, saturation and brightness values, instead of rounding it to the
nearest detectable color.
:returns:
Measured color. The color is described by a hue (0--359), a
saturation (0--100), and a brightness value (0--100).
:rtype: :class:`Color <.parameters.Color>`
"""
pass
Expand Down Expand Up @@ -196,56 +200,58 @@ def __init__(self, port):
def color(self, surface=True):
"""Scans the color of a surface or an external light source.
You choose which colors are detected using the
:meth:`.detectable_colors` method. By default, it detects
``Color.RED``, ``Color.YELLOW``, ``Color.GREEN``, ``Color.BLUE``,
``Color.WHITE``, or ``None``.
Arguments:
surface (bool): Choose ``true`` to scan the color of objects
and surfaces. Choose ``false`` to scan the color of
screens and other external light sources.
:returns:
Detected color.
:rtype: :class:`Color <.parameters.Color>`, or ``None`` if no color is
detected.
:rtype: :class:`Color <.parameters.Color>`
"""
pass

def color_map(self, hues, saturation, values):
"""Configures how :meth:`.color` selects a
:class:`Color <.parameters.Color>` based on a :meth:`.hsv` measurement.
def detectable_colors(self, colors):
"""Configures which colors the :meth:`.color` method should detect.
Specify only colors that you wish to detect in your application.
This way, measurements are
rounded to the nearest expected color, and other colors are ignored.
This way, the full-color measurements are rounded to the nearest
desired color, and other colors are ignored. This improves reliability.
If you give no arguments, the current settings will be returned as a
tuple.
If you give no arguments, the currently chosen colors will be returned
as a tuple.
Arguments:
hues (dict): A dictionary that
maps :class:`Color <.parameters.Color>` to hues. When the
saturation is high, :meth:`.color` will return one of these
colors, whichever has the nearest hue.
saturation (:ref:`percentage`): Minimum saturation of a proper
color.
values (:ref:`percentage`): A dictionary that
maps ``Color.WHITE``, ``Color.GRAY``, ``Color.BLACK`` and
``None`` to brightness values. When the saturation is
low, :meth:`.color` will return one of these colors, whichever
has the nearest value.
colors (list): List of :class:`Color <.parameters.Color>` objects:
the colors that you want to detect. You can pick
standard colors such as ``Color.MAGENTA``, or provide your own
colors like
``Color(h=348, s=96, v=40, name='MY_MAGENTA_BRICK')`` for even
better results. You measure your own colors with the
:meth:`.hsv` method.
"""
pass

def hsv(self, surface=True):
"""Scans the hue, saturation and brightness value of a
surface or an external light source.
"""Scans the color of a surface or an external light source.
This method is similar to :meth:`.color`, but it gives the full range
of hue, saturation and brightness values, instead of rounding it to the
nearest detectable color.
Arguments:
surface (bool): Choose ``true`` to scan the color of objects
and surfaces. Choose ``false`` to scan the color of
screens and other external light sources.
:returns: Tuple with the hue, saturation, and value
(brightness) of the color.
:rtype: (:ref:`hue`, :ref:`percentage`, :ref:`percentage`)
:returns:
Measured color. The color is described by a hue (0--359), a
saturation (0--100), and a brightness value (0--100).
:rtype: :class:`Color <.parameters.Color>`
"""
pass
Expand Down

0 comments on commit d6651fc

Please sign in to comment.