Michel2/pybricks-api
1
0
Fork 0
mirror of https://github.com/pybricks/pybricks-api.git synced 2026-09-11 09:05:07 +00:00
Code Issues Releases Activity

pybricks.hubs: Enable EV3.

Browse Source 
First pass including Image and ImageFile. Largely migrated from old ev3dev version. We can refine this for the embedded version in the next commits.
This commit is contained in:
Laurens Valk
2026-08-25 11:42:05 +02:00
parent 6a70707f67
commit adf8ed6b56
41 changed files with 702 additions and 2619 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/common/conf.py
-2
View File
@@ -193,8 +193,6 @@ htmlhelp_basename = "Pybricksdoc"
exclude_patterns = [
"hubs/ev3brick.rst",
"media.rst",
"messaging.rst",
"tools/datalog.rst",
"*.rst.txt",
doc/main/hubs/ev3brick.rst
+9 -125
View File
@@ -1,4 +1,4 @@
MINDSTORMS EV3 Brick
EV3 Brick
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. figure:: ../../main/cad/output/ev3device-ev3.png
@@ -17,20 +17,18 @@ MINDSTORMS EV3 Brick
.. automethod:: pybricks.hubs::EV3Brick.light.off
.. automethod:: pybricks.hubs::EV3Brick.light.blink
.. automethod:: pybricks.hubs::EV3Brick.light.animate
.. rubric:: Using the speaker
.. automethod:: pybricks.hubs::EV3Brick.speaker.volume
.. automethod:: pybricks.hubs::EV3Brick.speaker.beep
.. automethod:: pybricks.hubs::EV3Brick.speaker.play_notes
.. automethod:: pybricks.hubs::EV3Brick.speaker.play_file
.. automethod:: pybricks.hubs::EV3Brick.speaker.say
.. automethod:: pybricks.hubs::EV3Brick.speaker.set_speech_options
.. automethod:: pybricks.hubs::EV3Brick.speaker.set_volume
.. rubric:: Using the screen
.. |this image| replace:: the screen
@@ -60,10 +58,10 @@ MINDSTORMS EV3 Brick
.. automethod:: pybricks.hubs::EV3Brick.screen.draw_circle
.. autoattribute:: pybricks.hubs::EV3Brick.screen.width
:annotation: = 178
.. autoattribute:: pybricks.hubs::EV3Brick.screen.height
.. automethod:: pybricks.hubs::EV3Brick.screen.save
:annotation: = 128
.. rubric:: Using the battery
@@ -83,122 +81,8 @@ Turn the light on and change the color
Screen examples
---------------------
Show an image on the screen
***************************
.. literalinclude::
../../../examples/ev3/screen_image/main.py
Drawing shapes on the screen
****************************
.. literalinclude::
../../../examples/ev3/screen_draw/main.py
Using different fonts
*********************
.. raw:: latex
\begin{CJK}{UTF8}{gbsn}
.. literalinclude::
../../../examples/ev3/screen_print/main.py
.. raw:: latex
\end{CJK}
.. rubric:: Available languages and voices for speech
.. [#espeak_lang]
You can choose the following languages:
- ``'af'``: Afrikaans
- ``'an'``: Aragonese
- ``'bg'``: Bulgarian
- ``'bs'``: Bosnian
- ``'ca'``: Catalan
- ``'cs'``: Czech
- ``'cy'``: Welsh
- ``'da'``: Danish
- ``'de'``: German
- ``'el'``: Greek
- ``'en'``: English (default)
- ``'en-gb'``: English (United Kingdom)
- ``'en-sc'``: English (Scotland)
- ``'en-uk-north'``: English (United Kingdom, Northern)
- ``'en-uk-rp'``: English (United Kingdom, Received Pronunciation)
- ``'en-uk-wmids'``: English (United Kingdom, West Midlands)
- ``'en-us'``: English (United States)
- ``'en-wi'``: English (West Indies)
- ``'eo'``: Esperanto
- ``'es'``: Spanish
- ``'es-la'``: Spanish (Latin America)
- ``'et'``: Estonian
- ``'fa'``: Persian
- ``'fa-pin'``: Persian
- ``'fi'``: Finnish
- ``'fr-be'``: French (Belgium)
- ``'fr-fr'``: French (France)
- ``'ga'``: Irish
- ``'grc'``: Greek
- ``'hi'``: Hindi
- ``'hr'``: Croatian
- ``'hu'``: Hungarian
- ``'hy'``: Armenian
- ``'hy-west'``: Armenian (Western)
- ``'id'``: Indonesian
- ``'is'``: Icelandic
- ``'it'``: Italian
- ``'jbo'``: Lojban
- ``'ka'``: Georgian
- ``'kn'``: Kannada
- ``'ku'``: Kurdish
- ``'la'``: Latin
- ``'lfn'``: Lingua Franca Nova
- ``'lt'``: Lithuanian
- ``'lv'``: Latvian
- ``'mk'``: Macedonian
- ``'ml'``: Malayalam
- ``'ms'``: Malay
- ``'ne'``: Nepali
- ``'nl'``: Dutch
- ``'no'``: Norwegian
- ``'pa'``: Punjabi
- ``'pl'``: Polish
- ``'pt-br'``: Portuguese (Brazil)
- ``'pt-pt'``: Portuguese (Portugal)
- ``'ro'``: Romanian
- ``'ru'``: Russian
- ``'sk'``: Slovak
- ``'sq'``: Albanian
- ``'sr'``: Serbian
- ``'sv'``: Swedish
- ``'sw'``: Swahili
- ``'ta'``: Tamil
- ``'tr'``: Turkish
- ``'vi'``: Vietnamese
- ``'vi-hue'``: Vietnamese (Hue)
- ``'vi-sgn'``: Vietnamese (Saigon)
- ``'zh'``: Mandarin Chinese
- ``'zh-yue'``: Cantonese Chinese
You can choose the following voices:
- ``'f1'``: female variant 1
- ``'f2'``: female variant 2
- ``'f3'``: female variant 3
- ``'f4'``: female variant 4
- ``'f5'``: female variant 5
- ``'m1'``: male variant 1
- ``'m2'``: male variant 2
- ``'m3'``: male variant 3
- ``'m4'``: male variant 4
- ``'m5'``: male variant 5
- ``'m6'``: male variant 6
- ``'m7'``: male variant 7
- ``'croak'``: croak
- ``'whisper'``: whisper
- ``'whisperf'``: female whisper
doc/main/hubs/index.rst
+9
View File
@@ -14,6 +14,7 @@
technichub
primehub
essentialhub
ev3brick
.. pybricks-classlink:: MoveHub
@@ -50,3 +51,11 @@
.. figure:: ../../main/cad/output/hub-essential.png
:width: 25%
:target: essentialhub.html
.. pybricks-classlink:: EV3Brick
.. figure:: ../../main/cad/output/ev3device-ev3.png
:width: 25%
:target: ev3brick.html
doc/main/media.rst
-1679
View File
File diff suppressed because it is too large Load Diff
doc/main/parameters/font.rst
+31
View File
@@ -0,0 +1,31 @@
.. pybricks-requirements:: ev3
Font
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. autoclass:: pybricks.parameters.Font
:no-members:
.. autoattribute:: pybricks.parameters.Font.DEFAULT
:annotation:
.. autoattribute:: pybricks.parameters.Font.TERMINUS_16
:annotation:
.. autoattribute:: pybricks.parameters.Font.LIBERATIONSANS_14
:annotation:
.. autoattribute:: pybricks.parameters.Font.MONO_8X5_8
:annotation:
.. autoattribute:: pybricks.parameters.Font.family
.. autoattribute:: pybricks.parameters.Font.style
.. autoattribute:: pybricks.parameters.Font.width
.. autoattribute:: pybricks.parameters.Font.height
.. automethod:: pybricks.parameters.Font.text_width
.. automethod:: pybricks.parameters.Font.text_height
doc/main/parameters/image.rst
+59
View File
@@ -0,0 +1,59 @@
.. pybricks-requirements:: ev3
Image
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. |this image| replace:: this image
.. autoclass:: pybricks.parameters.Image
:no-members:
.. automethod:: pybricks.parameters.Image.empty
.. rubric:: Drawing text
There are two ways to draw text on images. :meth:`draw_text` lets text be
placed precisely on the image or :meth:`print` can be used to automatically
print text on a new line.
.. automethod:: pybricks.parameters.Image.draw_text
.. automethod:: pybricks.parameters.Image.print
.. automethod:: pybricks.parameters.Image.set_font
.. rubric:: Drawing images
A copy of another image can be drawn on an image. Also consider using
sub-images to copy part of an image.
.. automethod:: pybricks.parameters.Image.draw_image
.. rubric:: Drawing shapes
These are the methods to draw basic shapes, including points, lines,
rectangles and circles.
.. automethod:: pybricks.parameters.Image.draw_pixel
.. automethod:: pybricks.parameters.Image.draw_line
.. automethod:: pybricks.parameters.Image.draw_box
.. automethod:: pybricks.parameters.Image.draw_circle
.. rubric:: Image properties
.. autoattribute:: pybricks.parameters.Image.width
.. autoattribute:: pybricks.parameters.Image.height
.. rubric:: Replacing the entire image
.. automethod:: pybricks.parameters.Image.clear
.. automethod:: pybricks.parameters.Image.load_image
doc/main/parameters/imagefile.rst
+209
View File
@@ -0,0 +1,209 @@
.. pybricks-requirements:: ev3
ImageFile
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Note: Not all images are included in the firmware yet. This is a work in progress.
.. currentmodule:: pybricks.parameters
.. class:: ImageFile
.. rubric:: **Information**
.. data:: ACCEPT
.. image:: ../../../media/ev3dev-media/images/mono/information/accept.png
:width: 15 %
.. data:: BACKWARD
.. image:: ../../../media/ev3dev-media/images/mono/information/backward.png
:width: 15 %
.. data:: DECLINE
.. image:: ../../../media/ev3dev-media/images/mono/information/decline.png
:width: 15 %
.. data:: FORWARD
.. image:: ../../../media/ev3dev-media/images/mono/information/forward.png
:width: 15 %
.. data:: LEFT
.. image:: ../../../media/ev3dev-media/images/mono/information/left.png
:width: 15 %
.. data:: NO_GO
.. image:: ../../../media/ev3dev-media/images/mono/information/no_go.png
:width: 15 %
.. data:: QUESTION_MARK
.. image:: ../../../media/ev3dev-media/images/mono/information/question_mark.png
:width: 15 %
.. data:: RIGHT
.. image:: ../../../media/ev3dev-media/images/mono/information/right.png
:width: 15 %
.. data:: STOP_1
.. image:: ../../../media/ev3dev-media/images/mono/information/stop_1.png
:width: 15 %
.. data:: STOP_2
.. image:: ../../../media/ev3dev-media/images/mono/information/stop_2.png
:width: 15 %
.. data:: THUMBS_DOWN
.. image:: ../../../media/ev3dev-media/images/mono/information/thumbs_down.png
:width: 15 %
.. data:: THUMBS_UP
.. image:: ../../../media/ev3dev-media/images/mono/information/thumbs_up.png
:width: 15 %
.. data:: WARNING
.. image:: ../../../media/ev3dev-media/images/mono/information/warning.png
:width: 15 %
.. rubric:: **LEGO**
.. data:: EV3
.. image:: ../../../media/ev3dev-media/images/mono/lego/ev3.png
:width: 15 %
.. data:: EV3_ICON
.. image:: ../../../media/ev3dev-media/images/mono/lego/ev3_icon.png
:width: 15 %
.. rubric:: **Objects**
.. data:: TARGET
.. image:: ../../../media/ev3dev-media/images/mono/objects/target.png
:width: 15 %
.. rubric:: **Eyes**
.. data:: ANGRY
.. image:: ../../../media/ev3dev-media/images/mono/eyes/angry.png
:width: 15 %
.. data:: AWAKE
.. image:: ../../../media/ev3dev-media/images/mono/eyes/awake.png
:width: 15 %
.. data:: BOTTOM_LEFT
.. image:: ../../../media/ev3dev-media/images/mono/eyes/bottom_left.png
:width: 15 %
.. data:: BOTTOM_RIGHT
.. image:: ../../../media/ev3dev-media/images/mono/eyes/bottom_right.png
:width: 15 %
.. data:: CRAZY_1
.. image:: ../../../media/ev3dev-media/images/mono/eyes/crazy_1.png
:width: 15 %
.. data:: CRAZY_2
.. image:: ../../../media/ev3dev-media/images/mono/eyes/crazy_2.png
:width: 15 %
.. data:: DIZZY
.. image:: ../../../media/ev3dev-media/images/mono/eyes/dizzy.png
:width: 15 %
.. data:: DOWN
.. image:: ../../../media/ev3dev-media/images/mono/eyes/down.png
:width: 15 %
.. data:: EVIL
.. image:: ../../../media/ev3dev-media/images/mono/eyes/evil.png
:width: 15 %
.. data:: KNOCKED_OUT
.. image:: ../../../media/ev3dev-media/images/mono/eyes/knocked_out.png
:width: 15 %
.. data:: MIDDLE_LEFT
.. image:: ../../../media/ev3dev-media/images/mono/eyes/middle_left.png
:width: 15 %
.. data:: MIDDLE_RIGHT
.. image:: ../../../media/ev3dev-media/images/mono/eyes/middle_right.png
:width: 15 %
.. data:: NEUTRAL
.. image:: ../../../media/ev3dev-media/images/mono/eyes/neutral.png
:width: 15 %
.. data:: PINCHED_LEFT
.. image:: ../../../media/ev3dev-media/images/mono/eyes/pinched_left.png
:width: 15 %
.. data:: PINCHED_MIDDLE
.. image:: ../../../media/ev3dev-media/images/mono/eyes/pinched_middle.png
:width: 15 %
.. data:: PINCHED_RIGHT
.. image:: ../../../media/ev3dev-media/images/mono/eyes/pinched_right.png
:width: 15 %
.. data:: SLEEPING
.. image:: ../../../media/ev3dev-media/images/mono/eyes/sleeping.png
:width: 15 %
.. data:: TIRED_LEFT
.. image:: ../../../media/ev3dev-media/images/mono/eyes/tired_left.png
:width: 15 %
.. data:: TIRED_MIDDLE
.. image:: ../../../media/ev3dev-media/images/mono/eyes/tired_middle.png
:width: 15 %
.. data:: TIRED_RIGHT
.. image:: ../../../media/ev3dev-media/images/mono/eyes/tired_right.png
:width: 15 %
.. data:: UP
.. image:: ../../../media/ev3dev-media/images/mono/eyes/up.png
:width: 15 %
.. data:: WINKING
.. image:: ../../../media/ev3dev-media/images/mono/eyes/winking.png
:width: 15 %
doc/main/parameters/index.rst
+9
View File
@@ -14,7 +14,10 @@
button
color
direction
font
icon
image
imagefile
port
side
stop
@@ -27,8 +30,14 @@
.. pybricks-classlink:: Direction
.. pybricks-classlink:: Font
.. pybricks-classlink:: Icon
.. pybricks-classlink:: Image
.. pybricks-classlink:: ImageFile
.. pybricks-classlink:: Port
.. pybricks-classlink:: Side
examples/ev3/bluetooth_client/client.py
-2
View File
@@ -1,5 +1,3 @@
#!/usr/bin/env pybricks-micropython
# Before running this program, make sure the client and server EV3 bricks are
# paired using Bluetooth, but do NOT connect them. The program will take care
# of establishing the connection.
examples/ev3/bluetooth_read_spike/main.py
-1
View File
@@ -1,4 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.hubs import EV3Brick
from pybricks.tools import wait
examples/ev3/bluetooth_read_spike/rover.py
-1
View File
@@ -1,4 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.hubs import EV3Brick
from pybricks.tools import wait
from pybricks.ev3devices import Motor
examples/ev3/bluetooth_server/server.py
-2
View File
@@ -1,5 +1,3 @@
#!/usr/bin/env pybricks-micropython
# Before running this program, make sure the client and server EV3 bricks are
# paired using Bluetooth, but do NOT connect them. The program will take care
# of establishing the connection.
examples/ev3/buttons/main.py
-2
View File
@@ -1,5 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.hubs import EV3Brick
from pybricks.tools import wait
from pybricks.parameters import Button
examples/ev3/buttons_quickstart/main.py
-2
View File
@@ -1,5 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.hubs import EV3Brick
from pybricks.parameters import Button
examples/ev3/datalog/main.py
-1
View File
@@ -1,4 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.ev3devices import Motor
from pybricks.parameters import Port
from pybricks.tools import DataLog, StopWatch, wait
examples/ev3/datalog_extra/main.py
-1
View File
@@ -1,4 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.parameters import Color
from pybricks.tools import DataLog
examples/ev3/ev3devsensor/.gitignore
-3
View File
@@ -1,3 +0,0 @@
__pycache__/
*.pyc
venv/
examples/ev3/ev3devsensor/.vscode/extensions.json
Vendored
-13
View File
@@ -1,13 +0,0 @@
{
// See http://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
// Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
// List of extensions which should be recommended for users of this workspace.
"recommendations": [
"lego-education.ev3-micropython"
],
// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
"unwantedRecommendations": [
"ms-python.python"
]
}
examples/ev3/ev3devsensor/.vscode/launch.json
Vendored
-20
View File
@@ -1,20 +0,0 @@
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": "Main Example",
"type": "ev3devBrowser",
"request": "launch",
"program": "/home/robot/${workspaceRootFolderName}/main.py"
},
{
"name": "Class Example",
"type": "ev3devBrowser",
"request": "launch",
"program": "/home/robot/${workspaceRootFolderName}/class_example.py"
}
]
}
examples/ev3/ev3devsensor/.vscode/settings.json
Vendored
-6
View File
@@ -1,6 +0,0 @@
// Place your settings in this file to overwrite default and user settings.
{
"files.eol": "\n",
"debug.openDebug": "neverOpen",
"python.linting.enabled": false
}
examples/ev3/ev3devsensor/class_example.py
-45
View File
@@ -1,45 +0,0 @@
#!/usr/bin/env pybricks-micropython
from pybricks.parameters import Port
from pybricks.iodevices import Ev3devSensor
class MySensor(Ev3devSensor):
"""Example of extending the Ev3devSensor class."""
def __init__(self, port):
"""Initialize the sensor."""
# Initialize the parent class.
super().__init__(port)
# Get the sysfs path.
self.path = "/sys/class/lego-sensor/sensor" + str(self.sensor_index)
def get_modes(self):
"""Get a list of mode strings so we don't have to look them up."""
# The path of the modes file.
modes_path = self.path + "/modes"
# Open the modes file.
with open(modes_path, "r") as m:
# Read the contents.
contents = m.read()
# Strip the newline symbol, and split at every space symbol.
return contents.strip().split(" ")
# Initialize the sensor
sensor = MySensor(Port.S3)
# Show where this sensor can be found
print(sensor.path)
# Print the available modes
modes = sensor.get_modes()
print(modes)
# Read mode 0 of this sensor
val = sensor.read(modes[0])
print(val)
examples/ev3/ev3devsensor/main.py
-19
View File
@@ -1,19 +0,0 @@
#!/usr/bin/env pybricks-micropython
from pybricks.parameters import Port
from pybricks.tools import wait
from pybricks.iodevices import Ev3devSensor
# Initialize an Ev3devSensor.
# In this example we use the
# LEGO MINDSTORMS EV3 Color Sensor.
sensor = Ev3devSensor(Port.S3)
while True:
# Read the raw RGB values
r, g, b = sensor.read("RGB-RAW")
# Print results
print("R: {0}\t G: {1}\t B: {2}".format(r, g, b))
# Wait
wait(200)
examples/ev3/getting_started/main.py
-1
View File
@@ -1,4 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.hubs import EV3Brick
from pybricks.ev3devices import Motor
from pybricks.parameters import Port
examples/ev3/i2c_basics/main.py
-1
View File
@@ -1,4 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.hubs import EV3Brick
from pybricks.iodevices import I2CDevice
from pybricks.parameters import Port
examples/ev3/i2c_extra/main.py
-1
View File
@@ -1,4 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.hubs import EV3Brick
from pybricks.iodevices import I2CDevice
from pybricks.parameters import Port
examples/ev3/light_color/main.py
-2
View File
@@ -1,5 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.hubs import EV3Brick
from pybricks.tools import wait
from pybricks.parameters import Color
examples/ev3/ps4/main.py
-1
View File
@@ -1,4 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.ev3devices import Motor
from pybricks.parameters import Port
examples/ev3/rcx_touch/main.py
-1
View File
@@ -1,4 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.hubs import EV3Brick
from pybricks.iodevices import AnalogSensor
from pybricks.parameters import Port, Color
examples/ev3/screen_draw/main.py
-2
View File
@@ -1,5 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.hubs import EV3Brick
from pybricks.tools import wait
examples/ev3/screen_extra/main.py
-2
View File
@@ -1,5 +1,3 @@
#!/usr/bin/env pybricks-micropython
import math
from pybricks.hubs import EV3Brick
examples/ev3/screen_image/main.py
-2
View File
@@ -1,5 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.hubs import EV3Brick
from pybricks.tools import wait
from pybricks.media.ev3dev import Image, ImageFile
examples/ev3/screen_print/main.py
-2
View File
@@ -1,5 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.hubs import EV3Brick
from pybricks.tools import wait
from pybricks.media.ev3dev import Font
examples/ev3/speaker_basics/main.py
-2
View File
@@ -1,5 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.hubs import EV3Brick
from pybricks.tools import wait
from pybricks.media.ev3dev import SoundFile
examples/ev3/uart_basics/main.py
-1
View File
@@ -1,4 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.hubs import EV3Brick
from pybricks.iodevices import UARTDevice
from pybricks.parameters import Port
examples/ev3/vernier_surface_temperature/main.py
-1
View File
@@ -1,4 +1,3 @@
#!/usr/bin/env pybricks-micropython
from pybricks.parameters import Port
from pybricks.nxtdevices import VernierAdapter
src/pybricks/ev3dev/_speaker.py
-126
View File
@@ -1,126 +0,0 @@
# SPDX-License-Identifier: MIT
# Copyright (c) 2018-2021 The Pybricks Authors
from typing import Iterable, Union, Optional
from ..media.ev3dev import SoundFile
class Speaker:
"""Plays beeps and sounds using a speaker."""
def beep(self, frequency: int = 500, duration: int = 100) -> None:
"""beep(frequency=500, duration=100)
Play a beep/tone.
Arguments:
frequency (Number, Hz):
Frequency of the beep. Frequencies below 100 Hz are treated as
100 Hz.
duration (Number, ms):
Duration of the beep. If the duration is less than 0, then the
method returns immediately and the frequency play continues to
play indefinitely.
"""
def play_notes(self, notes: Iterable[str], tempo: int = 120) -> None:
"""play_notes(notes, tempo=120)
Plays a sequence of musical notes. For example:
``['C4/4', 'C4/4', 'G4/4', 'G4/4']``.
Each note is a string with the following format:
- The first character is the name of the note, ``A`` to ``G``
or ``R`` for a rest.
- Note names can also include an accidental ``#`` (sharp) or
``b`` (flat). ``B#``/``Cb`` and ``E#``/``Fb`` are not
allowed.
- The note name is followed by the octave number ``2``
to ``8``. For example ``C4`` is middle C. The octave changes
to the next number at the note C, for example, ``B3`` is the
note below middle C (``C4``).
- The octave is followed by ``/`` and a number that indicates
the size of the note. For example ``/4`` is a quarter note,
``/8`` is an eighth note and so on.
- This can optionally followed by a ``.`` to make a dotted
note. Dotted notes are 1-1/2 times as long as notes without a
dot.
- The note can optionally end with a ``_`` which is a tie or a
slur. This causes there to be no pause between this note and
the next note.
Arguments:
notes (iter):
A sequence of notes to be played.
tempo (int):
Beats per minute. A quarter note is one beat.
"""
def play_file(self, file_name: Union[SoundFile, str]) -> None:
"""play_file(file_name)
Plays a sound file.
Arguments:
file (str):
Path to the sound file, including the file extension.
"""
def say(self, text: str) -> None:
"""say(text)
Says a given text string.
You can configure the language and voice of the text using
:meth:`.set_speech_options`.
Arguments:
text (str): What to say.
"""
def set_speech_options(
self,
language: Optional[str] = None,
voice: Optional[str] = None,
speed: Optional[int] = None,
pitch: Optional[int] = None,
):
"""set_speech_options(language, voice, speed, pitch)
Configures speech settings used by the :meth:`.say` method.
Any option that is set to ``None`` will not be changed. If an option
is set to an invalid value :meth:`.say` will use the default value
instead.
Arguments:
language (str):
Language of the text. For example, you can choose ``'en'``
(English) or ``'de'`` (German). [#espeak_lang]_
voice (str):
The voice to use. For example, you can choose ``'f1'`` (female
voice variant 1) or ``'m3'`` (male voice variant 3).
[#espeak_lang]_
speed (int):
Number of words per minute.
pitch (int):
Pitch (0 to 99). Higher numbers make the voice higher pitched
and lower numbers make the voice lower pitched.
"""
def set_volume(self, volume: int, which: str = "_all_") -> None:
"""set_volume(volume, which="_all_")
Sets the speaker volume.
Arguments:
volume (Number, %):
Volume of the speaker.
which (str):
Which volume to set. ``'Beep'`` sets the volume for
`beep` and `play_notes`. ``'PCM'`` sets the
volume for :meth:`.play_file` and :meth:`.say`. ``'_all_'``
sets both at the same time.
"""
src/pybricks/hubs.py
+2 -4
View File
@@ -8,9 +8,7 @@ from __future__ import annotations
from typing import TYPE_CHECKING
from . import _common
from .ev3dev import _speaker
from .media.ev3dev import Image as _Image
from .parameters import Axis, Button as _Button
from .parameters import Axis, Button as _Button, Image as _Image
class EV3Brick:
@@ -28,7 +26,7 @@ class EV3Brick:
]
)
screen = _Image("_screen_")
speaker = _speaker.Speaker()
speaker = _common.Speaker()
battery = _common.Battery()
light = _common.ColorLight()
src/pybricks/media/__init__.py
View File
src/pybricks/media/ev3dev.py
-545
View File
@@ -1,545 +0,0 @@
# SPDX-License-Identifier: MIT
# Copyright (c) 2018-2020 The Pybricks Authors
"""Images and Sounds for Pybricks on ev3dev."""
from __future__ import annotations
from typing import Union, Literal, overload, Optional, Any
from ..parameters import Color
class Image:
"""Object representing a graphics image. This can either be an in-memory
copy of an image or the image displayed on a screen."""
# Documentation note: This class is also treated as the `screen` object
# on EV3 so we use |this image| when it would make sense to say "the screen"
# in that context and it is automatically replaced when the documentation
# is generated.
@overload
def __init__(self, /, source: Union[Image, ImageFile, str]): ...
@overload
def __init__(
self, /, source: Image, sub: Literal[False], x1: int, y1: int, x2: int, y2: int
): ...
def __init__(self, *args):
"""Image(source, sub=False)
Arguments:
source (str or Image):
The source of the image.
If ``source`` is a string, then the image will be loaded from
the file path given by the string. Only ``.png`` files are
supported. As a special case, if the string is ``_screen_``,
the image will be configured to draw directly on the screen.
If an :class:`Image` is given, the new object will contain a
copy of the ``source`` image object.
sub (bool):
If ``sub`` is ``True``, then the image object will act as a
sub-image of the ``source`` image (this only works if the type
of ``source`` is :class:`Image` and not when it is a ``str``).
Additional keyword arguments ``x1``, ``y1``, ``x2``, ``y2`` are
needed when ``sub=True``. These specify the top-left and
bottom-right coordinates in the ``source`` image that will be
used as the bounds for the sub-image.
"""
@property
def width(self) -> int:
"""Gets the width of |this image| in pixels."""
return 0
@property
def height(self) -> int:
"""Gets the height of |this image| in pixels."""
return 0
def clear(self) -> None:
"""clear()
Clears |this image|. All pixels on |this image| will be set to
:attr:`Color.WHITE <pybricks.parameters.Color.WHITE>`.
"""
def draw_pixel(self, x: int, y: int, color: Color = Color.BLACK) -> None:
"""draw_pixel(x, y, color=Color.BLACK)
Draws a single pixel on |this image|.
Arguments:
x (int): The x coordinate of the pixel.
y (int): The y coordinate of the pixel.
color (Color): The color of the pixel.
"""
def draw_line(
self,
x1: int,
y1: int,
x2: int,
y2: int,
width: int = 1,
color: Color = Color.BLACK,
) -> None:
"""draw_line(x1, y1, x2, y2, width=1, color=Color.BLACK)
Draws a line on |this image|.
Arguments:
x1 (int): The x coordinate of the starting point of the line.
y1 (int): The y coordinate of the starting point of the line.
x2 (int): The x coordinate of the ending point of the line.
y2 (int): The y coordinate of the ending point of the line.
width (int): The width of the line in pixels.
color (Color): The color of the line.
"""
def draw_box(
self,
x1: int,
y1: int,
x2: int,
y2: int,
r: int = 0,
fill: bool = False,
color: Color = Color.BLACK,
) -> None:
"""draw_box(x1, y1, x2, y2, r=0, fill=False, color=Color.BLACK)
Draws a box on |this image|.
Arguments:
x1 (int): The x coordinate of the left side of the box.
y1 (int): The y coordinate of the top of the box.
x2 (int): The x coordinate of the right side of the box.
y2 (int): The y coordinate of the bottom of the box.
r (int): The radius of the corners of the box.
fill (bool): If ``True``, the box will be filled with ``color``,
otherwise only the outline of the box will be drawn.
color (Color): The color of the box.
"""
def draw_circle(
self, x: int, y: int, r: int, fill: bool = False, color: Color = Color.BLACK
) -> None:
"""draw_circle(x, y, r, fill=False, color=Color.BLACK)
Draws a circle on |this image|.
Arguments:
x (int): The x coordinate of the center of the circle.
y (int): The y coordinate of the center of the circle.
r (int): The radius of the circle.
fill (bool): If ``True``, the circle will be filled with
``color``, otherwise only the circumference will be drawn.
color (Color): The color of the circle.
"""
def draw_image(
self,
x: int,
y: int,
source: Union[Image, ImageFile, str],
transparent: Optional[Color] = None,
) -> None:
"""draw_image(x, y, source, transparent=None)
Draws the ``source`` image on |this image|.
Arguments:
x (int):
The x-axis value where the left side of the image will start.
y (int):
The y-axis value where the top of the image will start.
source (Image or str):
The source :class:`Image <pybricks.media.ev3dev.Image>`. If
the argument is a string, then the ``source`` image is loaded
from file.
transparent (Color):
The color of ``image`` to treat as transparent or ``None`` for
no transparency.
"""
def load_image(self, source: Union[Image, ImageFile, str]) -> None:
"""load_image(source)
Clears this image, then draws the ``source`` image centered in
|this image|.
Arguments:
source (Image or str):
The source :class:`Image <pybricks.media.ev3dev.Image>`. If
the argument is a string, then the ``source`` image is loaded
from file.
"""
def draw_text(
self,
x: int,
y: int,
text: str,
text_color: Color = Color.BLACK,
background_color: Optional[Color] = None,
) -> None:
"""draw_text(x, y, text, text_color=Color.BLACK, background_color=None)
Draws text on |this image|.
The most recent font set using :meth:`.set_font` will be used or
:data:`Font.DEFAULT <pybricks.media.ev3dev.Font.DEFAULT>` if no font
has been set yet.
Arguments:
x (int):
The x-axis value where the left side of the text will start.
y (int):
The y-axis value where the top of the text will start.
text (str):
The text to draw.
text_color (Color):
The color used for drawing the text.
background_color (Color):
The color used to fill the rectangle behind the text or
``None`` for transparent background.
"""
def print(self, *args: Any, sep: str = " ", end: str = "\n") -> None:
"""print(*args, sep=" ", end="\\n")
Prints a line of text on |this image|.
This method works like the builtin ``print()`` function, but it writes
on |this image| instead.
You can set the font using :meth:`.set_font`. If no font has been set,
:data:`Font.DEFAULT <pybricks.media.ev3dev.Font.DEFAULT>` will be
used. The text is always printed used black text with a white
background.
Unlike the builtin ``print()``, the text does not wrap if it is too
wide to fit on |this image|. It just gets cut off. But if the text
would go off of the bottom of |this image|, the entire image is
scrolled up and the text is printed in the new blank area at the
bottom of |this image|.
Arguments:
args (Any): Zero or more objects to print.
sep (str): Separator that will be placed between each object that
is printed.
end (str): End of line that will be printed after the last object.
"""
def set_font(self, font: Font) -> None:
"""set_font(font)
Sets the font used for writing on |this image|.
The font is used for both :meth:`.draw_text` and :meth:`.print`.
Arguments:
font (Font):
The font to use.
"""
@staticmethod
def empty(width: int = 178, height: int = 128) -> Image:
"""empty(width=178, height=128) -> Image
Creates a new empty :class:`Image` object.
Arguments:
width (int):
The width of the image in pixels.
height (int):
The height of the image in pixels.
Returns:
A new image with all pixels set
to :attr:`Color.WHITE <pybricks.parameters.Color.WHITE>`.
Raises:
TypeError:
If ``width`` or ``height`` is not a number.
ValueError:
If ``width`` or ``height`` is less than 1.
RuntimeError:
If there was a problem allocating a new image.
"""
def save(self, filename: str) -> None:
"""save(filename)
Saves |this image| as a ``.png`` file.
Arguments:
filename (str):
The path to the file to be saved.
Raises:
TypeError:
``filename`` is not a string.
OSError:
There was a problem saving the file.
"""
class Font:
"""Object that represents a font for writing text."""
DEFAULT: Font = None # assigned later since we can't use Font() here
"""The default font."""
def __init__(
self,
family: Optional[str] = None,
size: int = 12,
bold: bool = False,
monospace: bool = False,
lang: Optional[str] = None,
script: Optional[str] = None,
):
"""Font(family=None, size=12, bold=False, monospace=False, lang=None, script=None)
The font object will be a font that is the "best" match based on the
parameters given and available fonts installed.
Arguments:
family (str):
The preferred font family or ``None`` to use the default value.
size (int):
The preferred font size. Most fonts have sizes between 6 and 24.
This is the "point" size and not the same as :attr:`height`.
bold (bool):
When ``True``, prefer bold fonts.
monospace (bool):
When ``True`` prefer monospaced fonts. This is useful for
aligning multiple rows of text.
lang (str):
A language code, such as ``'en'`` or ``'zh-cn'`` or ``None`` to
use the default language. [#font_lang]_
script (str):
A unicode script identifier such as ``'Runr'`` or ``None``.
"""
@property
def family(self) -> str:
"""Gets the family name of the font."""
return "Lucida"
@property
def style(self) -> str:
"""style -> str
Gets a string describing the font style.
Can be "Regular" or "Bold".
"""
return "Regular"
@property
def width(self) -> int:
"""Gets the width of the widest character of the font."""
return 0
@property
def height(self) -> int:
"""Gets the height of the font."""
return 0
def text_width(self, text: str) -> int:
"""text_width(text)
Gets the width of the text when the text is drawn using this font.
Arguments:
text (str):
The text.
Returns:
int:
The width in pixels.
"""
return 0
def text_height(self, text: str) -> int:
"""text_height(text)
Gets the height of the text when the text is drawn using this font.
Arguments:
text (str):
The text.
Returns:
int:
The height in pixels.
"""
return 0
Font.DEFAULT = Font("Lucida", 12)
class SoundFile:
"""Paths to standard EV3 sounds."""
_BASE_PATH: str = "/usr/share/sounds/ev3dev/"
SHOUTING: str = _BASE_PATH + "expressions/shouting.wav"
CHEERING: str = _BASE_PATH + "expressions/cheering.wav"
CRYING: str = _BASE_PATH + "expressions/crying.wav"
OUCH: str = _BASE_PATH + "expressions/ouch.wav"
LAUGHING_2: str = _BASE_PATH + "expressions/laughing_2.wav"
SNEEZING: str = _BASE_PATH + "expressions/sneezing.wav"
SMACK: str = _BASE_PATH + "expressions/smack.wav"
BOING: str = _BASE_PATH + "expressions/boing.wav"
BOO: str = _BASE_PATH + "expressions/boo.wav"
UH_OH: str = _BASE_PATH + "expressions/uh-oh.wav"
SNORING: str = _BASE_PATH + "expressions/snoring.wav"
KUNG_FU: str = _BASE_PATH + "expressions/kung_fu.wav"
FANFARE: str = _BASE_PATH + "expressions/fanfare.wav"
CRUNCHING: str = _BASE_PATH + "expressions/crunching.wav"
MAGIC_WAND: str = _BASE_PATH + "expressions/magic_wand.wav"
LAUGHING_1: str = _BASE_PATH + "expressions/laughing_1.wav"
LEFT: str = _BASE_PATH + "information/left.wav"
BACKWARDS: str = _BASE_PATH + "information/backwards.wav"
RIGHT: str = _BASE_PATH + "information/right.wav"
OBJECT: str = _BASE_PATH + "information/object.wav"
COLOR: str = _BASE_PATH + "information/color.wav"
FLASHING: str = _BASE_PATH + "information/flashing.wav"
ERROR: str = _BASE_PATH + "information/error.wav"
ERROR_ALARM: str = _BASE_PATH + "information/error_alarm.wav"
DOWN: str = _BASE_PATH + "information/down.wav"
FORWARD: str = _BASE_PATH + "information/forward.wav"
ACTIVATE: str = _BASE_PATH + "information/activate.wav"
SEARCHING: str = _BASE_PATH + "information/searching.wav"
TOUCH: str = _BASE_PATH + "information/touch.wav"
UP: str = _BASE_PATH + "information/up.wav"
ANALYZE: str = _BASE_PATH + "information/analyze.wav"
STOP: str = _BASE_PATH + "information/stop.wav"
DETECTED: str = _BASE_PATH + "information/detected.wav"
TURN: str = _BASE_PATH + "information/turn.wav"
START: str = _BASE_PATH + "information/start.wav"
MORNING: str = _BASE_PATH + "communication/morning.wav"
EV3: str = _BASE_PATH + "communication/ev3.wav"
GO: str = _BASE_PATH + "communication/go.wav"
GOOD_JOB: str = _BASE_PATH + "communication/good_job.wav"
OKEY_DOKEY: str = _BASE_PATH + "communication/okey-dokey.wav"
GOOD: str = _BASE_PATH + "communication/good.wav"
NO: str = _BASE_PATH + "communication/no.wav"
THANK_YOU: str = _BASE_PATH + "communication/thank_you.wav"
YES: str = _BASE_PATH + "communication/yes.wav"
GAME_OVER: str = _BASE_PATH + "communication/game_over.wav"
OKAY: str = _BASE_PATH + "communication/okay.wav"
SORRY: str = _BASE_PATH + "communication/sorry.wav"
BRAVO: str = _BASE_PATH + "communication/bravo.wav"
GOODBYE: str = _BASE_PATH + "communication/goodbye.wav"
HI: str = _BASE_PATH + "communication/hi.wav"
HELLO: str = _BASE_PATH + "communication/hello.wav"
MINDSTORMS: str = _BASE_PATH + "communication/mindstorms.wav"
LEGO: str = _BASE_PATH + "communication/lego.wav"
FANTASTIC: str = _BASE_PATH + "communication/fantastic.wav"
SPEED_IDLE: str = _BASE_PATH + "movements/speed_idle.wav"
SPEED_DOWN: str = _BASE_PATH + "movements/speed_down.wav"
SPEED_UP: str = _BASE_PATH + "movements/speed_up.wav"
BROWN: str = _BASE_PATH + "colors/brown.wav"
GREEN: str = _BASE_PATH + "colors/green.wav"
BLACK: str = _BASE_PATH + "colors/black.wav"
WHITE: str = _BASE_PATH + "colors/white.wav"
RED: str = _BASE_PATH + "colors/red.wav"
BLUE: str = _BASE_PATH + "colors/blue.wav"
YELLOW: str = _BASE_PATH + "colors/yellow.wav"
TICK_TACK: str = _BASE_PATH + "mechanical/tick_tack.wav"
HORN_1: str = _BASE_PATH + "mechanical/horn_1.wav"
BACKING_ALERT: str = _BASE_PATH + "mechanical/backing_alert.wav"
MOTOR_IDLE: str = _BASE_PATH + "mechanical/motor_idle.wav"
AIR_RELEASE: str = _BASE_PATH + "mechanical/air_release.wav"
AIRBRAKE: str = _BASE_PATH + "mechanical/airbrake.wav"
RATCHET: str = _BASE_PATH + "mechanical/ratchet.wav"
MOTOR_STOP: str = _BASE_PATH + "mechanical/motor_stop.wav"
HORN_2: str = _BASE_PATH + "mechanical/horn_2.wav"
LASER: str = _BASE_PATH + "mechanical/laser.wav"
SONAR: str = _BASE_PATH + "mechanical/sonar.wav"
MOTOR_START: str = _BASE_PATH + "mechanical/motor_start.wav"
INSECT_BUZZ_2: str = _BASE_PATH + "animals/insect_buzz_2.wav"
ELEPHANT_CALL: str = _BASE_PATH + "animals/elephant_call.wav"
SNAKE_HISS: str = _BASE_PATH + "animals/snake_hiss.wav"
DOG_BARK_2: str = _BASE_PATH + "animals/dog_bark_2.wav"
DOG_WHINE: str = _BASE_PATH + "animals/dog_whine.wav"
INSECT_BUZZ_1: str = _BASE_PATH + "animals/insect_buzz_1.wav"
DOG_SNIFF: str = _BASE_PATH + "animals/dog_sniff.wav"
T_REX_ROAR: str = _BASE_PATH + "animals/t-rex_roar.wav"
INSECT_CHIRP: str = _BASE_PATH + "animals/insect_chirp.wav"
DOG_GROWL: str = _BASE_PATH + "animals/dog_growl.wav"
SNAKE_RATTLE: str = _BASE_PATH + "animals/snake_rattle.wav"
DOG_BARK_1: str = _BASE_PATH + "animals/dog_bark_1.wav"
CAT_PURR: str = _BASE_PATH + "animals/cat_purr.wav"
EIGHT: str = _BASE_PATH + "numbers/eight.wav"
SEVEN: str = _BASE_PATH + "numbers/seven.wav"
SIX: str = _BASE_PATH + "numbers/six.wav"
FOUR: str = _BASE_PATH + "numbers/four.wav"
TEN: str = _BASE_PATH + "numbers/ten.wav"
ONE: str = _BASE_PATH + "numbers/one.wav"
TWO: str = _BASE_PATH + "numbers/two.wav"
THREE: str = _BASE_PATH + "numbers/three.wav"
ZERO: str = _BASE_PATH + "numbers/zero.wav"
FIVE: str = _BASE_PATH + "numbers/five.wav"
NINE: str = _BASE_PATH + "numbers/nine.wav"
READY: str = _BASE_PATH + "system/ready.wav"
CONFIRM: str = _BASE_PATH + "system/confirm.wav"
GENERAL_ALERT: str = _BASE_PATH + "system/general_alert.wav"
CLICK: str = _BASE_PATH + "system/click.wav"
OVERPOWER: str = _BASE_PATH + "system/overpower.wav"
class ImageFile:
"""Paths to standard EV3 images."""
_BASE_PATH: str = "/usr/share/images/ev3dev/mono/"
RIGHT: str = _BASE_PATH + "information/right.png"
FORWARD: str = _BASE_PATH + "information/forward.png"
ACCEPT: str = _BASE_PATH + "information/accept.png"
QUESTION_MARK: str = _BASE_PATH + "information/question_mark.png"
STOP_1: str = _BASE_PATH + "information/stop_1.png"
LEFT: str = _BASE_PATH + "information/left.png"
DECLINE: str = _BASE_PATH + "information/decline.png"
THUMBS_DOWN: str = _BASE_PATH + "information/thumbs_down.png"
BACKWARD: str = _BASE_PATH + "information/backward.png"
NO_GO: str = _BASE_PATH + "information/no_go.png"
WARNING: str = _BASE_PATH + "information/warning.png"
STOP_2: str = _BASE_PATH + "information/stop_2.png"
THUMBS_UP: str = _BASE_PATH + "information/thumbs_up.png"
EV3: str = _BASE_PATH + "lego/ev3.png"
EV3_ICON: str = _BASE_PATH + "lego/ev3_icon.png"
TARGET: str = _BASE_PATH + "objects/target.png"
BOTTOM_RIGHT: str = _BASE_PATH + "eyes/bottom_right.png"
BOTTOM_LEFT: str = _BASE_PATH + "eyes/bottom_left.png"
EVIL: str = _BASE_PATH + "eyes/evil.png"
CRAZY_2: str = _BASE_PATH + "eyes/crazy_2.png"
KNOCKED_OUT: str = _BASE_PATH + "eyes/knocked_out.png"
PINCHED_RIGHT: str = _BASE_PATH + "eyes/pinched_right.png"
WINKING: str = _BASE_PATH + "eyes/winking.png"
DIZZY: str = _BASE_PATH + "eyes/dizzy.png"
DOWN: str = _BASE_PATH + "eyes/down.png"
TIRED_MIDDLE: str = _BASE_PATH + "eyes/tired_middle.png"
MIDDLE_RIGHT: str = _BASE_PATH + "eyes/middle_right.png"
SLEEPING: str = _BASE_PATH + "eyes/sleeping.png"
MIDDLE_LEFT: str = _BASE_PATH + "eyes/middle_left.png"
TIRED_RIGHT: str = _BASE_PATH + "eyes/tired_right.png"
PINCHED_LEFT: str = _BASE_PATH + "eyes/pinched_left.png"
PINCHED_MIDDLE: str = _BASE_PATH + "eyes/pinched_middle.png"
CRAZY_1: str = _BASE_PATH + "eyes/crazy_1.png"
NEUTRAL: str = _BASE_PATH + "eyes/neutral.png"
AWAKE: str = _BASE_PATH + "eyes/awake.png"
UP: str = _BASE_PATH + "eyes/up.png"
TIRED_LEFT: str = _BASE_PATH + "eyes/tired_left.png"
ANGRY: str = _BASE_PATH + "eyes/angry.png"
src/pybricks/media/py.typed
View File
src/pybricks/parameters.py
+374 -1
View File
@@ -7,10 +7,13 @@ from __future__ import annotations
import os
from enum import Enum
from typing import TYPE_CHECKING
from typing import TYPE_CHECKING, overload
from .tools import Matrix as _Matrix, vector as _vector
if TYPE_CHECKING:
from typing import Any, Literal, Optional, Union
if TYPE_CHECKING or os.environ.get("SPHINX_BUILD") == "True":
Number = int | float
"""
@@ -562,3 +565,373 @@ class Icon:
| ⬜🟨⬜🟨⬜
| 🟨⬜⬜⬜🟨
"""
class Image:
"""Object representing a graphics image. This can either be an in-memory
copy of an image or the image displayed on a screen."""
# Documentation note: This class is also treated as the `screen` object
# on EV3 so we use |this image| when it would make sense to say "the screen"
# in that context and it is automatically replaced when the documentation
# is generated.
@overload
def __init__(self, /, source: Union[Image, ImageFile]): ...
@overload
def __init__(
self, /, source: Image, sub: Literal[False], x1: int, y1: int, x2: int, y2: int
): ...
def __init__(self, *args):
"""Image(source, sub=False)
Arguments:
source (Image):
The source image. The new object will contain a copy of
the ``source`` image object.
sub (bool):
If ``sub`` is ``True``, then the image object will act as a
sub-image of the ``source`` image.
Additional keyword arguments ``x1``, ``y1``, ``x2``, ``y2`` are
needed when ``sub=True``. These specify the top-left and
bottom-right coordinates in the ``source`` image that will be
used as the bounds for the sub-image.
"""
@property
def width(self) -> int:
"""Gets the width of |this image| in pixels."""
return 0
@property
def height(self) -> int:
"""Gets the height of |this image| in pixels."""
return 0
def clear(self) -> None:
"""clear()
Clears |this image|. All pixels on |this image| will be set to
:attr:`Color.WHITE <pybricks.parameters.Color.WHITE>`.
"""
def draw_pixel(self, x: int, y: int, color: Color = Color.BLACK) -> None:
"""draw_pixel(x, y, color=Color.BLACK)
Draws a single pixel on |this image|.
Arguments:
x (int): The x coordinate of the pixel.
y (int): The y coordinate of the pixel.
color (Color): The color of the pixel.
"""
def draw_line(
self,
x1: int,
y1: int,
x2: int,
y2: int,
width: int = 1,
color: Color = Color.BLACK,
) -> None:
"""draw_line(x1, y1, x2, y2, width=1, color=Color.BLACK)
Draws a line on |this image|.
Arguments:
x1 (int): The x coordinate of the starting point of the line.
y1 (int): The y coordinate of the starting point of the line.
x2 (int): The x coordinate of the ending point of the line.
y2 (int): The y coordinate of the ending point of the line.
width (int): The width of the line in pixels.
color (Color): The color of the line.
"""
def draw_box(
self,
x1: int,
y1: int,
x2: int,
y2: int,
r: int = 0,
fill: bool = False,
color: Color = Color.BLACK,
) -> None:
"""draw_box(x1, y1, x2, y2, r=0, fill=False, color=Color.BLACK)
Draws a box on |this image|.
Arguments:
x1 (int): The x coordinate of the left side of the box.
y1 (int): The y coordinate of the top of the box.
x2 (int): The x coordinate of the right side of the box.
y2 (int): The y coordinate of the bottom of the box.
r (int): The radius of the corners of the box.
fill (bool): If ``True``, the box will be filled with ``color``,
otherwise only the outline of the box will be drawn.
color (Color): The color of the box.
"""
def draw_circle(
self, x: int, y: int, r: int, fill: bool = False, color: Color = Color.BLACK
) -> None:
"""draw_circle(x, y, r, fill=False, color=Color.BLACK)
Draws a circle on |this image|.
Arguments:
x (int): The x coordinate of the center of the circle.
y (int): The y coordinate of the center of the circle.
r (int): The radius of the circle.
fill (bool): If ``True``, the circle will be filled with
``color``, otherwise only the circumference will be drawn.
color (Color): The color of the circle.
"""
def draw_image(
self,
x: int,
y: int,
source: Union[Image, ImageFile],
transparent: Optional[Color] = None,
) -> None:
"""draw_image(x, y, source, transparent=None)
Draws the ``source`` image on |this image|.
Arguments:
x (int):
The x-axis value where the left side of the image will start.
y (int):
The y-axis value where the top of the image will start.
source (Image):
The source :class:`Image <pybricks.parameters.Image>`.
transparent (Color):
The color of ``image`` to treat as transparent or ``None`` for
no transparency.
"""
def load_image(self, source: Union[Image, ImageFile]) -> None:
"""load_image(source)
Clears this image, then draws the ``source`` image centered in
|this image|.
Arguments:
source (Image):
The source :class:`Image <pybricks.parameters.Image>`.
"""
def draw_text(
self,
x: int,
y: int,
text: str,
text_color: Color = Color.BLACK,
background_color: Optional[Color] = None,
) -> None:
"""draw_text(x, y, text, text_color=Color.BLACK, background_color=None)
Draws text on |this image|.
The most recent font set using :meth:`.set_font` will be used or
:data:`Font.DEFAULT <pybricks.parameters.Font.DEFAULT>` if no font
has been set yet.
Arguments:
x (int):
The x-axis value where the left side of the text will start.
y (int):
The y-axis value where the top of the text will start.
text (str):
The text to draw.
text_color (Color):
The color used for drawing the text.
background_color (Color):
The color used to fill the rectangle behind the text or
``None`` for transparent background.
"""
def print(self, *args: Any, sep: str = " ", end: str = "\n") -> None:
"""print(*args, sep=" ", end="\\n")
Prints a line of text on |this image|.
This method works like the builtin ``print()`` function, but it writes
on |this image| instead.
You can set the font using :meth:`.set_font`. If no font has been set,
:data:`Font.DEFAULT <pybricks.parameters.Font.DEFAULT>` will be
used. The text is always printed used black text with a white
background.
Unlike the builtin ``print()``, the text does not wrap if it is too
wide to fit on |this image|. It just gets cut off. But if the text
would go off of the bottom of |this image|, the entire image is
scrolled up and the text is printed in the new blank area at the
bottom of |this image|.
Arguments:
args (Any): Zero or more objects to print.
sep (str): Separator that will be placed between each object that
is printed.
end (str): End of line that will be printed after the last object.
"""
def set_font(self, font: Font) -> None:
"""set_font(font)
Sets the font used for writing on |this image|.
The font is used for both :meth:`.draw_text` and :meth:`.print`.
Arguments:
font (Font):
The font to use.
"""
@staticmethod
def empty(width: int = 178, height: int = 128) -> Image:
"""empty(width=178, height=128) -> Image
Creates a new empty :class:`Image` object.
Arguments:
width (int):
The width of the image in pixels.
height (int):
The height of the image in pixels.
Returns:
A new image with all pixels set
to :attr:`Color.WHITE <pybricks.parameters.Color.WHITE>`.
Raises:
TypeError:
If ``width`` or ``height`` is not a number.
ValueError:
If ``width`` or ``height`` is less than 1.
RuntimeError:
If there was a problem allocating a new image.
"""
class Font:
"""Object that represents a font for writing text."""
DEFAULT: Font = ...
"""The default font."""
TERMINUS_16: Font = ...
"""The Terminus font with a height of 16 pixels."""
LIBERATIONSANS_14: Font = ...
"""The Liberation Sans regular font with a height of 14 pixels."""
MONO_8X5_8: Font = ...
"""A monospaced font with a height of 8 pixels and a width of 5 pixels."""
@property
def family(self) -> str:
"""Gets the family name of the font."""
return "Lucida"
@property
def style(self) -> str:
"""style -> str
Gets a string describing the font style.
Can be "Regular" or "Bold".
"""
return "Regular"
@property
def width(self) -> int:
"""Gets the width of the widest character of the font."""
return 0
@property
def height(self) -> int:
"""Gets the height of the font."""
return 0
def text_width(self, text: str) -> int:
"""text_width(text)
Gets the width of the text when the text is drawn using this font.
Arguments:
text (str):
The text.
Returns:
int:
The width in pixels.
"""
return 0
def text_height(self, text: str) -> int:
"""text_height(text)
Gets the height of the text when the text is drawn using this font.
Arguments:
text (str):
The text.
Returns:
int:
The height in pixels.
"""
return 0
class ImageFile:
"""Paths to standard EV3 images."""
_BASE_PATH: str = "/usr/share/images/ev3dev/mono/"
RIGHT: str = _BASE_PATH + "information/right.png"
FORWARD: str = _BASE_PATH + "information/forward.png"
ACCEPT: str = _BASE_PATH + "information/accept.png"
QUESTION_MARK: str = _BASE_PATH + "information/question_mark.png"
STOP_1: str = _BASE_PATH + "information/stop_1.png"
LEFT: str = _BASE_PATH + "information/left.png"
DECLINE: str = _BASE_PATH + "information/decline.png"
THUMBS_DOWN: str = _BASE_PATH + "information/thumbs_down.png"
BACKWARD: str = _BASE_PATH + "information/backward.png"
NO_GO: str = _BASE_PATH + "information/no_go.png"
WARNING: str = _BASE_PATH + "information/warning.png"
STOP_2: str = _BASE_PATH + "information/stop_2.png"
THUMBS_UP: str = _BASE_PATH + "information/thumbs_up.png"
EV3: str = _BASE_PATH + "lego/ev3.png"
EV3_ICON: str = _BASE_PATH + "lego/ev3_icon.png"
TARGET: str = _BASE_PATH + "objects/target.png"
BOTTOM_RIGHT: str = _BASE_PATH + "eyes/bottom_right.png"
BOTTOM_LEFT: str = _BASE_PATH + "eyes/bottom_left.png"
EVIL: str = _BASE_PATH + "eyes/evil.png"
CRAZY_2: str = _BASE_PATH + "eyes/crazy_2.png"
KNOCKED_OUT: str = _BASE_PATH + "eyes/knocked_out.png"
PINCHED_RIGHT: str = _BASE_PATH + "eyes/pinched_right.png"
WINKING: str = _BASE_PATH + "eyes/winking.png"
DIZZY: str = _BASE_PATH + "eyes/dizzy.png"
DOWN: str = _BASE_PATH + "eyes/down.png"
TIRED_MIDDLE: str = _BASE_PATH + "eyes/tired_middle.png"
MIDDLE_RIGHT: str = _BASE_PATH + "eyes/middle_right.png"
SLEEPING: str = _BASE_PATH + "eyes/sleeping.png"
MIDDLE_LEFT: str = _BASE_PATH + "eyes/middle_left.png"
TIRED_RIGHT: str = _BASE_PATH + "eyes/tired_right.png"
PINCHED_LEFT: str = _BASE_PATH + "eyes/pinched_left.png"
PINCHED_MIDDLE: str = _BASE_PATH + "eyes/pinched_middle.png"
CRAZY_1: str = _BASE_PATH + "eyes/crazy_1.png"
NEUTRAL: str = _BASE_PATH + "eyes/neutral.png"
AWAKE: str = _BASE_PATH + "eyes/awake.png"
UP: str = _BASE_PATH + "eyes/up.png"
TIRED_LEFT: str = _BASE_PATH + "eyes/tired_left.png"
ANGRY: str = _BASE_PATH + "eyes/angry.png"