1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
|
Misc. Classes
=============
.. automodule:: libavg.avg
:no-members:
.. autoclass:: Bitmap
Class representing a rectangular set of pixels in CPU memory. Bitmaps can be
obtained from any :py:class:`RasterNode` or loaded from disk. For nodes of type
:py:class:`ImageNode`, the current bitmap can be set as well. In general, huge
Bitmaps (e.g. width>65536) are supported as long as they fit into memory.
The layout of the pixels in the bitmap is described by its pixel format.
The names for pixel format constants are confusing. They try to follow logic,
but it's a bit elusive: In many cases, each component is described by a single
letter indicating the component's role in the pixel and a number indicating the
number of bits used for this component.
Components are named in the order they appear in memory. In the cases where
the name doesn't follow this logic, reasons for the name are usually historical or
by convention.
You can receive a complete list of all supported pixel formats by calling
:py:func:`avg.getSupportedPixelFormats()`.
The pixel formats are:
* :py:const:`B5G6R5`: 16 bits per pixel blue, green, red components.
* :py:const:`B8G8R8`: 24 bits per pixel blue, green, red components.
* :py:const:`B8G8R8A8`: 32 bits per pixel: blue, green, red and an
alpha (opacity) component.
* :py:const:`B8G8R8X8`: 32 bits per pixel, with the last byte unused.
* :py:const:`A8B8G8R8`
* :py:const:`X8B8G8R8`
* :py:const:`R5G6B5`
* :py:const:`R8G8B8`
* :py:const:`R8G8B8A8`
* :py:const:`R8G8B8X8`
* :py:const:`A8R8G8B8`
* :py:const:`X8R8G8B8`
* :py:const:`I8`: 8 bits of greyscale intensity.
* :py:const:`I16`: 16 bits of greyscale intensity.
* :py:const:`A8`: 8 bits of transparency information.
* :py:const:`YCbCr411`: Interleaved YCbCr: Y Y Cb Y Y Cr.
Effectively 12 bits per pixel. Output format of some cameras.
* :py:const:`YCbCr422`: Interleaved YCbCr: Cb Y Cr Y.
Effectively 16 bits per pixel. Output format of some cameras.
* :py:const:`YUYV422`: Like YCbCr422, but grey values come first, so the
order is Y Cb Y Cr.
* :py:const:`YCbCr420p`: Not a valid pixel format for a single bitmap, but
still a description of planar bitmap coding. Signifies separate
bitmaps for Y, Cb and Cr components, with Cb and Cr half as big in both x
and y dimensions. This is mpeg YCbCr, where the color components have
values from 16...235. Used by many video formats, including mpeg.
* :py:const:`YCbCrJ420p`: Same as YCbCr420p, but this is the jpeg version
with component values in the range 0...255. Used in video as well, for
instance in motion jpeg encoding.
* :py:const:`YCbCrA420p`: YCbCr420p with an additional alpha (transparency)
bitmap at full resolution. Used in flash video with transparency.
* :py:const:`BAYER8`: Bayer pattern. This is raw camera sensor data with
an unspecified pixel order. The other :py:const:`BAYER_XXX` constants
specify differing camera sensor arrangements.
* :py:const:`BAYER8_RGGB`
* :py:const:`BAYER8_GBRG`
* :py:const:`BAYER8_GRBG`
* :py:const:`BAYER8_BGGR`
* :py:const:`R32G32B32A32F`: 32 bits per channel float RGBA.
* :py:const:`I32F`: 32 bits per channel greyscale intensity.
.. py:method:: __init__(size, pixelFormat, name)
Creates an uninitialized bitmap of the given size and pixel format.
:py:attr:`name` is a name to be used in debug output.
.. py:method:: __init__(bitmap)
Creates a copy of an already existing bitmap.
.. py:method:: __init__(bitmap, tlPos, brPos)
Returns a rectangle inside an existing bitmap as a new bitmap. Note that the
pixels are not copied and write operations will therefore effect the
original bitmap as well.
.. py:method:: __init__(fileName)
Loads an image file from disk and returns it as bitmap object.
.. py:method:: blt(srcBmp, pos)
Copies the pixels of srcBmp into the current bitmap at pos.
.. py:method:: getAvg() -> float
Returns the average of all bitmap pixels.
.. py:method:: getChannelAvg(channel) -> float
Returns the average of one of the bitmap color channels (red, green or blue).
Used for automatic tests.
.. py:method:: getFormat()
Returns the bitmap's pixel format.
.. py:method:: getName() -> string
.. py:method:: getPixel(pos) -> (r,g,b,a)
Returns one image pixel as a color tuple. This should only be used
for single pixels, as it is very slow.
.. py:method:: getPixels() -> string
Returns the raw pixel data in the bitmap as a python string. This
method can be used to interface to the python imaging library PIL
(http://www.pythonware.com/products/pil/).
.. py:method:: getResized(newSize) -> Bitmap
Returns a new bitmap that is a resized version of the original.
.. py:method:: getSize() -> Point2D
Returns the size of the image in pixels.
.. py:method:: getStdDev() -> float
Returns the standard deviation of all bitmap pixels.
.. py:method:: save(filename)
Writes the image to a file. File format is determined using the
extension. Supported file types are those supported by gdk-pixbuf. This
includes at least png, jpeg, gif, tiff and xpixmaps.
.. py:method:: setPixels(pixels)
Changes the raw pixel data in the bitmap. Doesn't change dimensions
or pixel format. Can be used to interface to the python imaging
library PIL (http://www.pythonware.com/products/pil/).
:param string pixels: Image data.
.. py:method:: subtract(otherbitmap) -> bmp
Subtracts two bitmaps and returns the result. Used mainly to compare
test images with the intended results (along with :py:meth:`getAvg` and
:py:meth:`getStdDev`).
.. autoclass:: BitmapManager
(EXPERIMENTAL) Singleton class that allow an asynchronous load of bitmaps.
The instance is accessed by :py:meth:`get`.
.. py:method:: loadBitmap(fileName, callback, pixelformat=NO_PIXELFORMAT)
Asynchronously loads a file into a Bitmap. The provided callback is invoked
with a Bitmap instance as argument in case of a successful load or with a
RuntimeError exception instance in case of failure. The optional parameter
:py:attr:`pixelformat` can be used to convert the bitmap to a specific format
asynchronously as well.
.. py:classmethod:: get() -> BitmapManager
This method gives access to the BitmapManager instance.
.. py:method:: setNumThreads(numThreads)
Sets the number of threads used to load bitmaps. The default is a single
thread. This should generally be less than the number of logical cores
available.
.. autoclass:: CubicSpline(controlpoints)
Class that generates a smooth curve between control points using cubic
spline-based interpolation. For an introduction on spline interpolation,
see http://en.wikipedia.org/wiki/Spline_interpolation.
:param controlpoints:
A list of 2D coordinates. The x coordinates must be in increasing order.
.. py:method:: interpolate(x) -> y
Takes an x coordinate and delivers a corresponding y coordinate.
.. autoclass:: FontStyle(font="sans", variant="", color="FFFFFF", fontsize=15, indent=0, linespacing=-1, alignment="left", wrapmode="word", justify=False, letterspacing=0, aagamma=1, hint=True)
A :py:class:`FontStyle` object encapsulates all configurable font attributes in a
:py:class:`WordsNode`. It provides a way to set all relevant attributes
(:py:attr:`font`, :py:attr:`fontsize`, etc.) in one line of code. The attributes
correspond to the :py:class:`WordsNode` attributes; refer to the
:py:class:`WordsNode` reference for descriptions.
.. autoclass:: Logger
An python interface to libavg's logger.
It can be accessed as follows:
.. code-block:: python
import libavg
libavg.logger
**Logging**
.. py:method:: log(message, category, severity)
Logs a message if category is active or severity is at least
:py:const:`ERROR`.
:param category:
One of the categories listed or a custom category. Defaults to
:py:const:`Logger.Category.APP`.
:param severity:
One of the severities listed. Defaults to :py:const:`Logger.Severity.INFO`.
:param message: The log message string.
.. py:method:: critical(msg, category)
Shortcut to :py:meth:`log` with **severity=** :py:const:`Logger.Severity.CRIT`.
.. py:method:: error(msg, category)
Shortcut to :py:meth:`log` with **severity=** :py:const:`Logger.Severity.ERR`.
.. py:method:: warning(msg, category)
Shortcut to :py:meth:`log` with **severity=** :py:const:`Logger.Severity.WARN`.
.. py:method:: info(msg, category)
Shortcut to :py:meth:`log` with **severity=** :py:const:`Logger.Severity.INFO`.
.. py:method:: debug(msg, category)
Shortcut to :py:meth:`log` with **severity=** :py:const:`Logger.Severity.DBG`.
**Configuration**
.. py:method:: addSink(logger)
Add a python logger object to libavg's logging handlers.
The python logger gets the key `category` as an "extra" kwarg, useful for
formatting the output.
.. py:method:: removeSink(logger)
Remove a previously added logger. It will not receive any messages dispatched
by the logger annymore. It's safe to call the function even if the logger is
not present.
.. py:method:: removeStdLogSink()
Remove libavg console printing sink.
Setting :envvar:`AVG_LOG_OMIT_STDERR` as EnvironmentVar has the same effect.
.. py:method:: configureCategory(category, severity)
Assign a severity to a given category.
category is either a custom string or a :py:const:`Logger.Category`
severity has to be one of :py:const:`Logger.Severity`, or it will default to
:py:const:`Logger.Severity.None`
.. py:method:: getCategories()
Returns a dict with **category** as key and **severity** as value
The Logger can also be configured using :envvar:`AVG_LOG_CATEGORIES` with
the format:
.. code-block:: bash
CATEGORY[:SEVERITY] [CATEGORY[:SEVERITY]]...
Thus it is possible to set a severity level for every category.
If no severity is given, the default severity is used.
(refer to: :py:meth:`setDefaultSeverity`)
If the category does not exist, it will be created.
.. code-block:: bash
export AVG_LOG_CATEGORIES="CONFIG:INFO APP:DBG PROFILE:DBG MEMORY"
Default categories are :py:const:`NONE`, :py:const:`APP` and
:py:const:`DEPREC`. They are set to the defaultSeverity.
**Categories:**
:py:const:`APP`
Reserved for application-level messages issued by python code.
:py:const:`CONFIG`
Outputs configuration data.
:py:const:`DEPREC`
Deprecation
Messages that warn of functionality that will be removed from libavg
in the future.
:py:const:`EVENTS`
Outputs basic event data.
:py:const:`MEMORY`
Outputs open/close information whenever a media file is accessed.
:py:const:`NONE`
Outputs everything that has not been categorized.
:py:const:`PROFILE`
Outputs performance statistics on player termination.
:py:const:`PROFILE_V`
Outputs performance statistics for video decoding.
:py:const:`PLUGIN`
Messages generated by loading plugins.
:py:const:`PLAYER`
General libavg playback messages.
:py:const:`SHADER`
Shader compiler messages.
**Severities**
:py:const:`CRIT` Critical
:py:const:`ERR` Error
:py:const:`WARN` Warning
:py:const:`INFO` Info
:py:const:`DBG` Debug
:py:const:`NONE` None
.. autoclass:: Point2D([x,y=(0,0)])
A point in 2D space. Supports most arithmetic operations on vectors. The
operators :py:attr:`+`, :py:attr:`-`, :py:attr:`==` and :py:attr:`\!=` are
defined for two :py:class:`Point2D` parameters. Unary :py:attr:`-` (negation)
is defined as well. :py:class:`Point2D` objects can also be multiplied and
divided by a scalar.
:py:class:`Point2D` implicitly converts from and to 2-element float tuples and
lists, so in most cases you can use one of these types whenever a point is needed.
.. py:attribute:: x
.. py:attribute:: y
.. py:method:: getAngle() -> float
Returns the direction of the vector as an angle between pi and -pi, with
0 being the positive x axis. Angles run clockwise.
.. py:method:: getNorm() -> float
Returns the euclidian norm of the point, that is sqrt(x*x+y*y).
.. py:method:: getNormalized() -> Point2D
Returns a normalized version of the point with the same angle but a
norm of one. Throws an exception if called on Point2D(0,0).
.. py:method:: getRotated(angle) -> Point2D
Return the position of point rotated around the origin.
.. py:method:: getRotated(angle, pivot) -> Point2D
Return the position of point rotated around :py:attr:`pivot`.
.. py:classmethod:: fromPolar(angle, radius) -> Point2D
Converts polar to cartesian coordinates. :py:attr:`angle` is in radians with 0
being the positive x axis. Angle is clockwise (assuming that y points
downward).
.. autoclass:: SVG(filename, [unescapeIllustratorIDs=False])
:py:class:`SVG` objects load and parse an svg file and render images from it.
svg (*Scalable Vector Graphics*, see http://en.wikipedia.org/wiki/Svg) files are
xml-based and contain two-dimensional vector graphics. They can be created with
editors such as Adobe Illustrator and Inkscape. :py:class:`SVG` objects can render
elements in the file to bitmaps and create image nodes from elements in the file.
Since the files contain vector graphics, the elements can be scaled to any size
when rendering without loss of resolution.
:param filename: The name of the file to load.
:param unescapeIllustratorIDs:
If this is :py:const:`True`, the file is assumed to be generated by Adobe
Illustrator. Illustrator mangles element names to create IDs in the svg file.
Setting this parameter to :py:const:`True` allows these element names to be
passed as IDs.
.. py:method:: renderElement(elementID, [size | scale=1]) -> Bitmap
Renders an element to a :py:class:`Bitmap`. Either :py:attr:`scale` or
:py:attr:`size` may be given. :py:attr:`size` is the size of the bitmap.
:py:attr:`scale` is a factor to scale the native bitmap size with.
.. py:method:: createImageNode(elementID, nodeAttrs, [size | scale=1]) -> Node
Convenience method that calls :py:meth:`renderElement` to render a bitmap
and then creates an image node that displays that bitmap. :py:attr:`nodeAttrs`
is a dictionary containing constructor parameters for the node.
.. py:method:: getElementPos(elementID) -> Point2D
Returns the position of an element.
.. py:method:: getElementSize(elementID) -> Point2D
Returns the original size of an element.
.. autoclass:: TestHelper
Miscellaneous routines used by tests. Not intended for normal application usage.
.. autoclass:: VersionInfo
Exposes version data, including the specs of the builder.
.. py:attribute:: full
Full string containing a compact form of branch and revision number (if the
build doesn't come from an exported tree)
.. py:attribute:: release
String representation in the form `major.minor.micro`
.. py:attribute:: major
Integer component of the release version (major)
.. py:attribute:: minor
Integer component of the release version (minor)
.. py:attribute:: micro
Integer component of the release version (micro)
.. py:attribute:: revision
Revision number, if applicable, or 0
.. py:attribute:: branchurl
Full URL path that represents the branch root, if applicable, or empty string
.. py:attribute:: builder
String representation in the form of `user@hostname machinespecs`
.. py:attribute:: buildtime
ISO timestamp representation of the build
.. autoclass:: VideoWriter(canvas, filename, [framerate=30, qmin=3, qmax=5, synctoplayback=True])
Class that writes the contents of a canvas to disk as a video file. The videos
are written as motion jpeg-encoded mov files. Writing commences immediately upon
object construction and continues until :py:meth:`stop` is called.
:py:meth:`pause` and :py:meth:`play` can be used to pause and resume writing.
The VideoWriter is built for high performance: Opening, writing and closing the
video file is asynchronous to normal playback. Writing full HD videos of
offscreen canvasses to disk should cost virtually no time on the main thread of
execution for an Intel Core-class processor with a graphics card that supports
shaders.
:param canvas:
A libavg canvas used as source of the video.
.. py:attribute:: filename
The name of the file to write to. Read-only.
.. py:attribute:: framerate
The speed of the encoded video in frames per second. This is used for two
purposes. First, it determines the nominal playback speed of the video that is
encoded in the file. Second, if :py:attr:`synctoplayback` is
:py:const:`False`, the :py:class:`VideoWriter` will also use the
:py:attr:`framerate` value as the actual number of frames per second to
write. Read-only.
.. py:attribute:: qmin
.. py:attribute:: qmax
:py:attr:`qmin` and :py:attr:`qmax` specify the minimum and maximum encoding
quality to use. :samp:`qmin = qmax = 1` give maximum quality at maximum file
size. :samp:`qmin=3` and :samp:`qmax=5` (the default) give a good quality and
a smaller file. Read-only.
.. py:attribute:: synctoplayback
If :py:attr:`synctoplayback` is :py:const:`True` (the default), each frame
played back in the canvas will be written to disk. This makes a lot of sense
in combination with :py:meth:`Canvas.registerCameraNode()`. If not,
:py:attr:`framerate` is used to determine which frames to write to disk. For
instance, if :py:attr:`synctoplayback` is :py:const:`False`,
:py:attr:`framerate` is 25 and the player is running at 60 fps, one movie
frame will be written for each 2.5 frames of playback. The actual, not the
nominal playback speed is used in this case. Read-only.
.. py:method:: pause()
Temporarily stops recording.
.. py:method:: play()
Resumes recording after a call to :py:meth:`pause`. :py:meth:`play` doesn't
need to be called after construction of the :py:class:`VideoWriter` - writing
commences immediately.
.. py:method:: stop()
Ends the recording and writes the rest of the file to disk. Note that this is
asynchronous to normal playback. If you need to immediately re-open the
video file (e.g. for playback in a video node), destroy the python object
first. This waits for sync.
.. autofunction:: getMemoryUsage() -> int
Returns the amount of memory used by the application in bytes. More
precisely, this function returns the resident set size of the process
in bytes. This does not include shared libraries or memory paged out to
disk.
.. autofunction:: pointInPolygon(point, poly) -> bool
Checks if a point is inside a polygon.
:param Point2D point: Point to check.
:param poly: List of points which constitute a polygon to check against.
:returns: :py:const:`True` if point is inside, :py:const:`False` otherwise.
.. autofunction:: validateXml(xmlString, schemaString, xmlName, schemaName)
Validates an xml string using a schema. Throws an exception if the xml doesn't
conform to the schema.
.. automodule:: libavg.statemachine
:no-members:
.. autoclass:: StateMachine(name, startState)
A generic state machine, useful for user interface and other states. Consists of
a set of states (represented by strings) and possible transitions between the
states. The :py:class:`StateMachine` can be configured to invoke callbacks at
specific transitions and when entering or leaving a state. All callbacks are
optional. State changes can be logged for debugging purposes.
State machines are initialized by calling :py:meth:`addState` for each
possible state after constructing it.
:param String name:
A name for the state machine to be used in debugging output.
:param String startState:
.. py:attribute:: state
The current state the :py:class:`StateMachine` is in. States are strings.
.. py:method:: addState(state, transitions, [enterFunc=None, leaveFunc=None])
Adds a state to the :py:class:`StateMachine`. Must be called before the first
changeState.
:param String state: The name of the state to add.
:param transitions:
This parameter can be either a list of destination states or a dict of
destinationState: callable pairs. The callables are invoked whenever the
corresponding state change happens. If :py:meth:`transitions` is a list,
no state change callbacks are registered.
:param enterFunc: A callable to invoke whenever the state is entered.
:param leaveFunc: A callable to invoke whenever the state is left.
.. py:method:: changeState(newState)
Changes the state. This includes calling the leave callback for the current
state, actually changing the state, calling the transition callback and
calling the enter callback for the new state.
Raises a :py:class:`RuntimeError` if :py:attr:`newState` is not a valid state
or if there is no transition defined from the current state to
:py:attr:`newState`.
.. py:method:: dump()
Prints all states and transitions to the console.
.. py:method:: makeDiagram(imageFName, [showMethods=False])
Dumps a graph of the state machine to an image file using dot. graphviz must
be installed and in the path for this to work. Very useful for debugging. If
:py:attr:`showMethods` is true, names of enter, leave and transition
methods are included in the diagram.
.. py:method:: traceChanges(trace)
If :py:attr:`trace` is set to :py:const:`True`, all state changes are dumped
to the console.
.. automodule:: libavg.persist
:no-members:
.. autoclass:: Persist(storeFile, initialData[, validator=lambda v: True, autoCommit=False])
A general purpose persistent object.
Its state is defined in the :py:attr:`data` attribute and pickled
from/to a store file.
:param string storeFile:
Full path of the store file that is used to store and retrieve a
serialized version of the data.
:param initialData:
A pickle-able object that is assigned to the :py:attr:`data` attribute
when no file store exists or when the store file is corrupted.
:param callable validator:
An optional callable that receives the object state as soon it's
de-pickled from the store file. If the validator call doesn't return True,
the object state is restored to the provided `initialData`.
:param bool autoCommit:
If True, the :py:attr:`commit` method is registered as an `atexit` function.
.. py:attribute:: data
State of the persistent object.
.. py:attribute:: storeFile
Returns the full path of the store file.
.. py:method:: commit()
Dumps the contents of the :py:attr:`data` attribute to the store file.
.. autoclass:: UserPersistentData(appName, fileName, initialData[, validator=lambda v: True, autoCommit=False])
A :py:class:`Persist` subclass that sets up an OS-independent path for
the store file.
Under posix-compliant OSes is `$HOME/.avg/<appName>/<fileName>.pkl`
Under Windows is `%APPDATA%\Avg\<appName>/<fileName>.pkl`
:param string appName:
Name of the application. This string is used to compose the full path to
the file store and it creates a namespace (directory) for multiple files
for the same application.
:param string fileName:
Name of the file store file. `.pkl` will be added as extension.
|