media – Sounds and Images¶
This module describes media such as sound and images that you can use in your projects. Media are divided into submodules that indicate on which platform they are available.
media.ev3dev – Sounds and Images¶
EV3 MicroPython is built on top of ev3dev, which comes with a variety of image and sound files. You can access them using the classes below.
You can also use your own sound and image files by placing them in your project folder.
Image Files¶
Sound Files¶
-
class
SoundFile¶ Paths to standard EV3 sounds.
Expressions
Information
Communication
Movement sounds
Colors
Mechanical
Animal sounds
Numbers
System sounds
Fonts¶
-
class
Font(family=None, size=12, bold=False, monospace=False, lang=None, script=None)¶ Object that represents a font for writing text.
The font object will be a font that is the “best” match based on the parameters given and available fonts installed.
Parameters: - family (str) – The preferred font family or
Noneto 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
height. - bold (bool) – When
True, prefer bold fonts. - monospace (bool) – When
Trueprefer monospaced fonts. This is useful for aligning multiple rows of text. - lang (str) – A language code, such as
'en'or'zh-cn'orNoneto use the default language. [1] - script (str) – A unicode script identifier such as
'Runr'orNone.
[1] Language codes
Note: Languages depend on installed fonts. Additional language codes are possible and some listed language codes may not have a satisfactory font.
'aa': Afar'af': Afrikaans'an': Aragonese'av': Avaric'ay': Aymara'az-az': Azerbaijani'be': Belarusian'bg': Bulgarian'bi': Bislama'bm': Bambara'br': Breton'bs': Bosnian'bua': Buriat'ca': Catalan'ce': Chechen'ch': Chamorro'co': Corsican'crh': Crimean'cs': Czech'csb': Kashubian'cy': Welsh'da': Danish'de': German'ee': Ewe'el': Greek'en': English'eo': Esperanto'es': Spanish'et': Estonian'eu': Basque'ff': Fulah'fi': Finnish'fil': Filipino'fj': Fijian'fo': Faroese'fr': French'fur': Friulian'fy': Western Frisian'ga': Irish'gd': Gaelic'gl': Galician'gv': Manx'ha': Hausa'haw': Hawaiian'he': Hebrew'ho': Hiri Motu'hr': Croatian'hsb': Upper Sorbian'ht': Haitian'hu': Hungarian'ia': Interlingua'id': Indonesian'ie': Interlingue'ik': Inupiaq'io': Ido'is': Icelandic'it': Italian'ja': Japanese'jv': Javanese'ki': Kikuyu'kj': Kuanyama'kl': Kalaallisut'ko': Korean'ku-tr': Kurdish'kum': Kumyk'kw': Cornish'kwm': Kwambi'la': Latin'lb': Luxembourgish'lez': Lezghian'lg': Ganda'li': Limburgan'ln': Lingala'lt': Lithuanian'lv': Latvian'mg': Malagasy'mh': Marshallese'mi': Maori'mk': Macedonian'mn-mn': Mongolian'mo': Moldavian'ms': Malay'mt': Maltese'na': Nauru'nb': Norwegian Bokmål'nds': Low German'ng': Ndonga'nl': Dutch'nn': Norwegian Nynorsk'no': Norwegian'nr': South Ndebele'nso': Northern Sotho'nv': Navajo'ny': Chichewa'oc': Occitan'om': Oromo'os': Ossetian'pap-an': Papiamento, Netherlands Antilles'pap-aw': Papiamento, Aruba'pl': Polish'pt': Portuguese'qu': Quechua'quz': Cusco Quechua'rm': Romansh'rn': Rundi'ro': Romanian'ru': Russian'rw': Kinyarwanda'sc': Sardinian'sco': Scots'se': Northern Sami'sel': Selkup'sg': Sango'sk': Slovak'sl': Slovenian'sm': Samoan'sma': Southern Sami'smj': Lule Sami'smn': Inari Sami'sms': Skolt Sami'sn': Shona'so': Somali'sq': Albanian'sr': Serbian'ss': Swati'st': Southern Sotho'su': Sundanese'sv': Swedish'sw': Swahili'tk': Turkmen'tl': Tagalog'tn': Tswana'to': Tonga'tr': Turkish'ts': Tsonga'ty': Tahitian'uk': Ukrainian'uz': Uzbek'vo': Volapük'vot': Votic'wa': Walloon'wen': Sorbian'wo': Wolof'xh': Xhosa'yap': Yapese'yi': Yiddish'za': Zhuang'zh-cn': Chinese, China'zh-sg': Chinese, Singapore'zh-tw': Chinese, Taiwan'zu': Zulu
-
DEFAULT= Font('Lucida', 12)¶ The default font.
-
family¶ Gets the family name of the font.
-
style¶ Gets a string describing the font style.
Can be “Regular” or “Bold”.
-
width¶ Gets the width of the widest character of the font.
-
height¶ Gets the height of the font.
-
text_width(text)¶ Gets the width of the text when the text is drawn using this font.
Parameters: text (str) – The text. Returns: The width in pixels. Return type: int
-
text_height(text)¶ Gets the height of the text when the text is drawn using this font.
Parameters: text (str) – The text. Returns: The height in pixels. Return type: int
Exploring more fonts
Behind the scenes, Pybricks uses Fontconfig for fonts. The Fontconfig command line tools can be used to explore available fonts in more detail. To do so, go to the ev3dev device browser, right click on your EV3 brick, and click Open SSH Terminal. Then you can enter one of these commands:
# List available font families. fc-list :scalable=false family # Perform lookup similar to Font.DEFAULT fc-match :scalable=false:dpi=119:family=Lucida:size=12 # Perform lookup similar to Font(size=24,lang=zh-cn) fc-match :scalable=false:dpi=119:size=24:lang=zh-cn
Pybricks only allows the use of bitmap fonts (
scalable=false) and the screen on the EV3 has 119 pixels per inch (dpi=119).- family (str) – The preferred font family or
Image Manipulation¶
Instead of drawing directly on the EV3 screen, you can make and interact
with image files using the Image class given below.
-
class
Image(source, sub=False)¶ Object representing a graphics image. This can either be an in-memory copy of an image or the image displayed on a screen.
Parameters: - source (str or Image) –
The source of the image.
If
sourceis a string, then the image will be loaded from the file path given by the string. Only.pngfiles are supported. As a special case, if the string is_screen_, the image will be configured to draw directly on the screen.If an
Imageis given, the new object will contain a copy of thesourceimage object. - sub (bool) –
If
subisTrue, then the image object will act as a sub-image of thesourceimage (this only works if the type ofsourceisImageand not when it is astr).Additional keyword arguments
x1,y1,x2,y2are needed whensub=True. These specify the top-left and bottom-right coordinates in thesourceimage that will be used as the bounds for the sub-image.
-
static
empty(width=<screen width>, height=<screen height>)¶ Creates a new empty
Imageobject.Parameters: - 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
Color.WHITE.Return type: Raises: TypeError–widthorheightis not a number.ValueError–widthorheightis less than 1.RuntimeError– There was a problem allocating a new image.
Drawing text
There are two ways to draw text on images.
draw_text()lets text be placed precisely on the image orprint()can be used to automatically print text on a new line.-
draw_text(x, y, text, text_color=Color.BLACK, background_color=None)¶ Draws text on this image.
The most recent font set using
set_font()will be used orFont.DEFAULTif no font has been set yet.Parameters: - 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
Nonefor transparent background.
-
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
set_font(). If no font has been set,Font.DEFAULTwill 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.Parameters: - * (object) – 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.
-
set_font(font)¶ Sets the font used for writing on this image.
The font is used for both
draw_text()andprint().Parameters: font ( Font) – The font to use.
Drawing images
A copy of another image can be drawn on an image. Also consider using sub-images to copy part of an image.
-
draw_image(x, y, source, transparent=None)¶ Draws the
sourceimage on this image.Parameters: - 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
Image. If the argument is a string, then thesourceimage is loaded from file. - transparent (Color) – The color of
imageto treat as transparent orNonefor no transparency.
Drawing shapes
These are the methods to draw basic shapes, including points, lines, rectangles and circles.
-
draw_pixel(x, y, color=Color.BLACK)¶ Draws a single pixel on this image.
Parameters: - x (int) – The x coordinate of the pixel.
- y (int) – The y coordinate of the pixel.
- color (Color) – The color of the pixel.
-
draw_line(x1, y1, x2, y2, width=1, color=Color.BLACK)¶ Draws a line on this image.
Parameters: - 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.
-
draw_box(x1, y1, x2, y2, r=0, fill=False, color=Color.BLACK)¶ Draws a box on this image.
Parameters: - 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 withcolor, otherwise only the outline of the box will be drawn. - color (Color) – The color of the box.
-
draw_circle(x, y, r, fill=False, color=Color.BLACK)¶ Draws a circle on this image.
Parameters: - 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 withcolor, otherwise only the circumference will be drawn. - color (Color) – The color of the circle.
Image properties
-
width¶ Gets the width of this image in pixels.
-
height¶ Gets the height of this image in pixels.
Replacing the entire image
-
clear()¶ Clears this image. All pixels on this image will be set to
Color.WHITE.
-
load_image(source)¶ Clears this image, then draws the
sourceimage centered in this image.Parameters: source (Image or str) – The source Image. If the argument is a string, then thesourceimage is loaded from file.
Saving the image
-
save(filename)¶ Saves this image as a
.pngfile.Parameters: filename (str) – The path to the file to be saved.
Raises: TypeError–filenameis not a string.OSError– There was a problem saving the file.
- source (str or Image) –