Shady.Utilities Sub-module
This module contains various optional (but useful) utility functions.
Note that everything exported from this module is also available in
the top-level Shady.*
namespace.
- Shady.Utilities.AutoFinish(world, shell=False, prefer_ipython=True, plot='auto')
A useful call at the end of a demo script, to navigate the various ways in which the script, and any
Shady.World
that was created in it, might be running (single- or dual-threaded by direct interpretation of the script; dual-threaded with theWorld
running in the main thread and the script interpreted in a subsidiary thread viapython -m Shady
).- Parameters:
world – A
World
instance, ready to run.shell (bool) – Whether or not to spawn a threaded interactive shell while the
World
is running.prefer_ipython (bool) – If a threaded shell is used, this indicates whether to try. to import the third-party package
IPython
to improve the interactive experience. If this isFalse
, or ifIPython
is not installed, then any interactive prompt spawned byshell=True
will be a plain-vanilla Python prompt.plot – This argument can be:
a callable function with zero arguments: in this case it is called when
world
finishes running; then it is assumed that one or morematplotlib
figures have been generated by the call and that they should be kept alive and responsive.a boolean specifying whether
matplotlib
figures already exist that need to be kept alive and responsive whenworld
finishes running.'auto'
(default): Ifworld.debugTiming
isTrue
, then callPlotTimings( world )
whenworld
finishes running. If not, infer automatically whether there arematplotlib
figures.
- Returns:
None
- Shady.Utilities.CheckPattern(canvasSize=(1920, 1080), amplitude=1.0, checkSize=1, meanZero=True)
Return a 2-dimensional
numpy.array
containing a checkerboard pattern.- Parameters:
canvasSize – may be an
int
(resulting in a square stimulus), or a sequence of two numbers (width, height). May also be aShady.World
instance,Shady.Stimulus
instance, aPIL
image, or an image represented as a 2- or 3-dimensionalnumpy.array
- in these cases the dimensions of the output match the dimensions of the instance.amplitude (float) – 0.0 means blank, 1.0 means full contrast.
checkSize (int) – size, in pixels, of the individual light and dark squares making up the checkerboard pattern.
meanZero (bool) – if
True
, then the mean of the output array is 0 and its range is[-1,1]
whenamplitude=1
. IfFalse
, then the mean of the output array is 0.5 and the range is[0,1]
whenamplitude=1
.
- Returns:
A two-dimensional
numpy.array
containing the image pixel values.
Examples:
world.Stimulus( CheckPattern( world ) * 0.5 + 0.5 ) world.Stimulus( CheckPattern( world, meanZero=False ) ) # same as above
- class Shady.Utilities.CommandLine(argv=None, dashes=2, caseSensitive=True, doc='')
c = CommandLine()
Create the object. Uses
argv=sys.argv[1:]
by default, as well asdoc=__doc__
.c.Option(...)
Define an option. By default, the option name and resolved value will be stored as key and value in the dict
c.opts
. If you specify anothercontainer
it will be stored there instead (and if you saycontainer=None
, it will not be stored anywhere). In any case the resolved value will also be returned fromOption()
c.Help()
Define and process the
--help
option: if it was supplied, print documentation and then eithersys.exit()
orraise CommandLineHelp()
.c.Finalize()
Issue an error if there are unrecognized options.
c.Delegate()
An alternative to
Finalize()
. Returnsargv
with all already-recognized options removed, so you can pass it to the nextCommandLine
parser in the cascade (in cases where you have more than one).
- Error
alias of
CommandLineError
- OptionValueError
alias of
CommandLineValueError
- UsagePrinted
alias of
CommandLineHelp
- Shady.Utilities.ComplexPolygonBase(nsides, appendNaN=True, joined=False)
Return a 1-by-n
numpy.array
of complex numbers that describe the vertices of a polygon.- Parameters:
nsides (int) – number of sides (or vertices) of the polygon.
appendNaN (bool) – whether to append a NaN (interpreted as a break between polygons in the
Stimulus.points
property).joined (bool) – whether to repeat the first vertex explicitly at the end. Only necessary if you want to draw unfilled (i.e. wireframe) closed polygons.
- Returns:
a 1-by-n
numpy.array
of complex numbers, wheren
isnsides
, plus 1 ifappendNaN
is True, plus 1 ifjoined
is True.
Example:
from Shady import World, ComplexPolygonBase, Real2DToComplex w = World(1000) s = w.Stimulus( drawMode=Shady.DRAWMODE.POLYGON, anchor=-1, color=[1,0,0] ) shape = 50 * ComplexPolygonBase( 12 ) locations = 150 * ComplexPolygonBase( 3, appendNaN=False ).T s.points = shape + locations
See also
- Shady.Utilities.ComplexToReal2D(x)
Given a single complex number
x
, return[ x.real, x.imag ]
. Or, by extension, given a single scalar real numberx
, return[ float(x), 0.0 ]
.Alternatively, if
x
is a sequence (i.e. a list, tuple or numpy array) of complex numbers, convert to an n-by-2 array of real-valued coordinates.Inverse of
Real2DToComplex()
- Shady.Utilities.Cross(world=None, size=13, thickness=3, **props)
Create an image of a simple cross (horizontal and vertical strokes) and optionally render it as a
Stimulus
object.- Parameters:
world (World) – Optional. If supplied, the image will be rendered as a
Stimulus
withz=-0.9
andlinearMagnification=False
. If omitted, the function will simply return the array of pixel values.size (int) – Desired dimensions of the final image, in pixels. For symmetry, if
thickness
is odd,size
should also be odd; and ifthickness
is even,size
should also be even. Otherwisesize
will get reduced by 1.thickness (int) – Thickness of the strokes of the cross, in pixels.
**props – Optional properties to be applied to the
Stimulus
object (ignored ifworld
is not supplied).
- Returns:
If a
World
instanceworld
is supplied, returns aStimulus
instance. Otherwise just return the array of pixel values.
- Shady.Utilities.DegreesToPixels(extentInDegrees, screenInfo, eccentricityInDegrees=0)
Compute the extent of a stimulus in pixels, given the number of degrees of visual arc it subtends and its eccentricity in degrees away from the line of sight.
- Parameters:
extentInDegrees – an
int
,float
or sequence/array of numbers, denoting the number of degrees subtended at the eye by the stimulus.screenInfo – either the input (a filename or a
dict
) or the output (a floating-point number) ofVDP()
.eccentricityInDegrees – an
int
,float
or sequence/array of numbers, denoting the angle in degrees between the line of sight and the line from the eye to the center of the stimulus
- Returns:
a
float
(for scalar inputs) or anumpy.array
(for array inputs) denoting stimulus extent(s) in pixels.
See also
- Shady.Utilities.EllipticalTukeyWindow(size, plateauProportion=0.0)
This function constructs a two-dimensional
numpy.array
of the specifiedsize
containing a discretely sampled one- or two-dimensional spatial windowing function. The function has an optional plateau in the center, outside of which it falls off to 0 according to a raised cosine profile. For two-dimensional windows, all contours of the array are elliptical and have the same aspect ratio as the specifiedsize
.This function replicates the formula that is used for windowing on the GPU, as per the fragment shader program at the heart of Shady.
- Parameters:
size – May be an integer (dictating a square output), a sequence of two integers [width, height], a
World
orStimulus
instance, or an existing 2- or 3-Dnumpy.array
to use as a template (i.e. one whose first two dimensions are [height, width] ).plateauProportion – This is either a single floating-point number, or a sequence of two numbers corresponding to the horizontal and vertical dimensions. The numbers specify the linear proportion of the cross section of the window function that is at maximum. They can be in the range 0.0 (no plateau => radial Hann window) to 1.0 (all plateau, no skirt => sharp-edged circle or ellipse). Alternatively, negative values can be used to disable windowing (so, for example,
[0.0, -1.0]
specifies Hann windowing in the horizontal dimension only, and no windowing in the vertical).
- Returns:
A two-dimensional
numpy.array
containing image pixel multipliers, in the range [0.0, 1.0].
- Shady.Utilities.EstimateFrameRate(world, nIdentical=10, nMaxFrames=100, nWarmUpFrames=10, threshold=1, wait=True)
DOC-TODO
- Shady.Utilities.FindGamma(world, finish=None, xBlue=True, text=False, **kwargs)
Interactively use a
LinearizationTestPattern
to estimate the correct gamma.Blank patches are interspersed in checkerboard fashion with textured patches. Textured patches contain horizontal stripes, vertical stripes, and checkerboard patterns, all of single-pixel granularity. Textured patches vary in contrast. When the screen (or stimulus) is perfectly linearized, textured patches of all contrasts should be indistinguishable from blank patches when viewed from a sufficient distance (or with sufficiently bad uncorrected vision).
The interactive component works best with touch-screens, but you can use the mouse. Up-down movement changes the overall gamma. With the option
xBlue=True
, left-right movement will also adjust the “color temperature” by varying the blue gamma relative to the others (without this, even when the overall gamma is neither too high nor too low, the textured patches can look yellower than the blank patches on some screens).Supply an optional callback as
finish
. When you press the return key, the adjustment procedure will end andfinish( gamma )
will be called with the final empirical gamma values. If you press the escape key instead, the adjustment will end by callingfinish( None )
instead. Press any letter key to report the current gamma setting on the console.
- class Shady.Utilities.FrameIntervalGauge(world, corner=(-1, -1), thickness=49, variable='width', color=(0, 0, 0), useTexture=True, rulerMaxMsec=50)
Display an animated gauge that visually records the frame-to-frame interval in milliseconds. Every millisecond is marked in blue; every ten milliseconds in red. To avoid overhead, no text is rendered.
- Shady.Utilities.Hann(x, rise=0.5, start=0.0)
A Hann window (raised cosine) function of
x
. Wraps around the more generalTukey()
function but ensures no plateau, and equal lengths of rise and fall.
- Shady.Utilities.Histogram(img, plot=True, DACmax=255, title=None, xlabel='Red, Green or Blue DAC Value', ylabel='Number of Pixels')
Takes an array of pixel values (for example, a
Stimulus.Capture()
output) and computes histograms of the luminance values in each channel. Optionally, plots the histograms.Requires the third-party package
numpy
to compute histograms, andmatplotlib
if you want to plot them.
- Shady.Utilities.LinearizationTestPattern(canvasSize=(1920, 1080), patchSize=(50, 50), amplitudes=(0.95, 0.75, 0.5, 0.25), plateauProportion=0.85, meanZero=True)
Construct a 2-dimensional
numpy.array
containing a special linearization pattern. Blank patches are interspersed in checkerboard fashion with textured patches. Textured patches contain horizontal stripes, vertical stripes, and checkerboard patterns, all of single-pixel granularity. Textured patches vary in contrast. When the screen (or stimulus) is perfectly linearized, textured patches of all contrasts should be indistinguishable from blank patches when viewed from a sufficient distance (or with sufficiently bad uncorrected vision).- Parameters:
canvasSize – may be an
int
(resulting in a square stimulus), or a sequence of two numbers (width, height). May also be aShady.World
instance,Shady.Stimulus
instance, aPIL
image, or an image represented as a 2- or 3-dimensionalnumpy.array
- in these cases the dimensions of the output match the dimensions of the instance.patchSize (sequence of 2 ints) – dimensions, in pixels, of the individual patches that make up the pattern in checkerboard fashion.
amplitudes (tuple of floats) – 0.0 means blank, 1.0 means full contrast.
plateauProportion (float) – governs the one-dimensional raised-cosine fading at the edges of striped patches. With
plateauProportion=1
, bright and dark edge artifacts tend to be visible.meanZero (bool) – if
True
, then the mean of the output array is 0 and its range is[-1,1]
whenamplitude=1
. IfFalse
, then the mean of the output array is 0.5 and the range is[0,1]
whenamplitude=1
.
- Returns:
A two-dimensional
numpy.array
containing the image pixel values.
Examples:
world.Stimulus( LinearizationTestPattern( world ) * 0.5 + 0.5 ) world.Stimulus( LinearizationTestPattern( world, meanZero=False ) ) # same as above
- Shady.Utilities.Loupe(target, update_period=1.0, **kwargs)
Given a
target
instance of classStimulus
, create anotherStimulus
instance that presents a magnified, contrast-enhanced, slowed-down (or rather, temporally sub-sampled) view of the pixels rendered by thetarget
.The returned instance has the following additional attributes:
target
: aweakref.ref
to thetarget
instanceupdate_period
: a floating-point number of secondsupdate_now
: a boolean which, if set toTrue
, forces an update on the next frame (and which is then automatically set back toFalse
).
NB: raw (post-linearization) pixel values are captured from the target and then rendered on the loupe which is itself, necessarily, unlinearized. At extreme values, color-contrast-enhancement may therefore lead to an apparent change in mean luminance even though there is no such change in the target.
- Shady.Utilities.PixelRuler(base, steps=((10, (0, 0, 1)), (100, (1, 0, 0)), (1000, (0, 1, 0))), alpha=None, topDown=False, world=None, oscillateGamma=False)
If
base
is an image size specification, or aWorld
instance, create a 90%-contrast grayCheckPattern()
of the appropriate size, to use as a base. Alternatively,base
may be a ready-made image.Draw grid lines over the base: the first pixel (pixel 0) is not colored. The 10th, 20th, 30th,… pixels (i.e. pixels 9, 19, 29, …) are blue. Similarly every 100th pixel is red, and every 1000th pixel is green.
The
topDown
argument changes the definition of “first pixel”: the default istopDown=False
, which means the first pixel is the bottom row and we work upwards, just like Shady’s normal coordinate system. But if you specifytopDown=True
, the first pixel is on the top row and we work downwards (the way one would index rows of a matrix).If
base
is aWorld
instance, or ifworld
is supplied as a separate argument, render the pattern at a depth ofz=0.9
and return the correspondingStimulus
instance. Otherwise just return the texture as anumpy
array.When rendering as a stimulus, the
oscillateGamma
argument may be useful. Non-zero values cause the stimulusgamma
property to oscillate between 1.0 and 3.0 as a function of time. The pixel values set byPixelRuler
, as well as those of the underlying defaultCheckPattern
, are all either 1.0 or 0.0—therefore, changes ingamma
should not be visible. The oscillation becomes visible if there is any spatial interpolation of pixel values, so it is a useful tool for highlighting any unintended geometric anomalies that violate the pixel-for-pixel assumption (sub-pixel shifts, non-90-degree rotations, scaling).
- Shady.Utilities.PixelsToDegrees(extentInPixels, screenInfo, eccentricityInPixels=0)
Compute the number of degrees of visual angle subtended by a stimulus of given its extent in pixels, and its distance from the point of fixation in pixels.
- Parameters:
extentInPixels – an
int
,float
or sequence/array of numbers, denoting the size of the stimulus in pixels.screenInfo – either the input (a filename or a
dict
) or the output (a floating-point number) ofVDP()
.eccentricityInPixels – an
int
,float
or sequence/array of numbers, denoting the distance between fixation and the center of the stimulus, in pixels.
- Returns:
a
float
(for scalar inputs) or anumpy.array
(for array inputs) denoting angle(s) subtended, in degrees of visual arc.
See also
- Shady.Utilities.PlotTimings(arg, savefig=None, traces=(), axes=None, finish=True, **kwargs)
Plot a graph of the recent timing diagnostics from a
World
instance or log-file name.The information is richer if the
World
instance, and even more so if individualStimulus
instances, haddebugTiming
set to True.Requires the third-party packages
numpy
andmatplotlib
.
- Shady.Utilities.Real2DToComplex(x, add_dims_left=0, add_dims_right='auto')
Given an n-by-2 array of real-valued coordinates, return the coordinates as an array of complex numbers (default shape n-by-1, but depends on
add_dims_left
andadd_dims_right
).Alternatively, given one coordinate expressed as a 2-element numeric sequence (i.e. a list, tuple or 1-D numpy array of length 2), return a single complex number.
Inverse of
ComplexToReal2D()
- Shady.Utilities.RelativeLocation(loc, obj, anchor=None, normalized=False)
Translate a two-dimensional location
loc
…- From:
World
coordinates (i.e. pixels relative to theWorld
’s currentanchor
position)- To:
coordinates relative to the current
xy
position of aStimulus
instance in the sameWorld
, or (optionally) relative to a differentanchor
position of theStimulus
instance.
- Parameters:
loc – input coordinates, in pixels (single scalar or sequence of two scalars)
obj –
Shady.Stimulus
orShady.World
instanceanchor – By default, the return value is expressed as an offset in pixels relative to the anchor position of
obj
(so, if obj is aStimulus
, the function just subtractsobj.xy
; or ifobj
is theWorld
, the output value will be equal to the input value).However, if you specify an explicitanchor
(2 numbers each in the range[-1, +1]
) then the return value will be re-expressed as a pixel offset relative to some other part ofobj
. For example, withanchor=[-1,-1]
you would get pixel coordinates relative to the bottom left corner ofobj
, or withanchor=[0,+1]
you get pixel coordinates relative to the middle of the top edge ofobj
. Theanchor
argument is ignored if you specifynormalized=True
.normalized (bool) – If
False
, return 2-D coordinates in pixels. IfTrue
, ignoreanchor
and return 2-D coordinates in the normalized coordinate system ofobj
. This effectively makes this function the inverse ofobj.Place()
.
- Returns:
[x, y]
coordinates, in pixels or normalized units depending on thenormalized
argument.
See also
Stimulus.Place()
World.Place()
- Shady.Utilities.RunShadyScript(*argv, **kwargs)
If a script name is specified, run it. If not, run an interactive prompt. In either case, interpret the commands in a new subsidiary thread—the main thread will be reserved. Construction and running of one
Shady.World
, if performed in the script or from the prompt, will be diverted to the main thread. This allows Shady applications to run in multi-threaded mode even on non-Windows operating systems, on which the graphical back-end insists on being in the main thread.With a script, the
console
option allows the script to run in demo mode, in which sections of the code can be run from an interactive prompt.This routine is used under the hood when you start Python with
-m Shady
. Here are some pairs of commands that produce equivalent results starting from outside and from inside Python:python -m Shady demo showcase --> RunShadyScript( 'showcase', console='IPython' ) python -m Shady run showcase --> RunShadyScript( 'showcase', console=None ) python -m Shady run showcase --console=Python --> RunShadyScript( 'showcase', console='Python' )
- Parameters:
*argv – positional arguments, just as you would use from a system command-line. If the first element
is sys.argv
thensys.argv[1:]
will be used plus any subsequent*argv
and**kwargs
arguments.**kwargs – optional keyword arguments, just as you would specify
--key=value
options from the command-line.
If you specify neither
argv
norkwargs
, thensys.argv[1:]
will be used. Options are as follows:--script
(or positional argument 0)The name of a Python script to run. If your script argument is not a valid (absolute or relative) path to an existing file, Shady will make a second attempt to find the named script inside the
examples
subdirectory of theShady
package itself (adding apy
extension if necessary). If no script is specified, an interactive prompt will be opened instead.--console
Values can be
'None'
,'Python'
or'IPython'
, specifying a preference for the type of interactive prompt that should be interleaved with script execution. The default is'IPython'
although Shady will fall back to'Python'
if the third-partyIPython
package is not available.'None'
will only be respected if a script has been specified, and it causes the script to be run without any interaction from the console.
- Shady.Utilities.TearingTest(world, period_sec=4.0, proportional_width=0.15)
Show a high-contrast bar oscillating from side to side, allowing visual inspection of possible “tearing” artifacts.
- Shady.Utilities.Tukey(x, rise=0.5, plateau=0.0, fall='rise', start=0.0)
This is a one-dimensional windowing function consisting of a raised- cosine rise from zero, an optional plateau, and a raised-cosine fall back to zero. It is a generalization of the Hann function. It requires the
numpy
package to be installed.- Parameters:
x – The input argument to the function, in units of space or time (let’s assume it’s time from here on).
rise – In the same units as
x
, the amount of time the function takes to rise from 0.0 to 1.0.plateau – In the same units as
x
, the amount of time for which the function remains at 1.0 between the rising and falling phases. The default is 0, which means this function returns a simple Hann or raised-cosine function by default.fall – In the same units as
x
, the amount of time the function takes to fall from 1.0 back to 0.0. Alternatively, the string'rise'
may be used (and it is the default) which makes the duration of the fall match the duration of the rise.start – In the same units as
x
, the initial amount of time for which the function remains at 0.0 before starting to rise. Defaults to 0.
- Returns:
The numeric output of the window function (as a
float
if the inputx
was a scalar numeric; as anumpy.array
ifx
was a sequence or array of numbers).
- Shady.Utilities.VDP(*pargs, **kwargs)
Return viewing distance measured in pixels, based on a set of configuration parameters. This allows easy conversion between degrees and pixels.
If a single scalar numeric argument is provided, return it unchanged.
If a string is provided, treat it the name of a Python file which defines the necessary settings as variables, and execute it.
If a
Shady.World
object is provided, inferwidthInPixels
andheightInPixels
from its size. Otherwise, if adict
is provided, take the necessary settings from that.Use
**kwargs
to augment / override settings.The necessary settings are:
viewingDistanceInMm
, and- EITHER:
widthInPixels
ANDwidthInMm
OR:
heightInPixels
ANDheightInMm
- EITHER:
Flexibility is allowed with these variable names: they are case-invariant and underscore-invariant, the
'In'
is optional, and the physical units can be mm, cm or m. So for example:viewing_distance_cm = 75
would give the same result as:
ViewingDistanceInMm = 750
Example:
v = VDP( world, heightInMm=169, viewingDistanceInCm=75 ) pixelsPerDegree = DegreesToPixels( 1.0, v )
- class Shady.Utilities.VideoRecording(filename, fps=60.0, codec='mp4v', container='.avi')
This class allows frames (in the form of
numpy
arrays) to be written to a video file. It wraps theVideoWriter
class from OpenCV.It requires third-party packages
numpy
andcv2
(the latter being part ofopencv-python
).Write frames with
WriteFrame()
. Remember toClose()
when finished.Example (capture video of one particular
Stimulus
):world = Shady.World( canvas=True, gamma=-1, noise=-0.1 ) stim = world.Stimulus( sigfunc=1, siga=0.4, pp=0, cx=lambda t:t*100, atmosphere=world ) world.fakeFrameRate = 60.0 # ensures accurate slower-than-real-time animation # (because .Capture() operations may be slow) movie = Shady.VideoRecording( 'example_movie', fps=world ) world.OnClose( movie.Close ) @stim.AnimationCallback def StimFrame( self, t ): movie.WriteFrame( self ) # we can pass a frame directly as a `numpy` array, # or we can pass a `Stimulus` or `World` instance # in which case its `.Capture()` method will be # called automatically world.Run()
- Parameters:
filename (str) – stem, or name, or path, to the video file to be saved. If
filename
includes a file extension, the container format is inferred from that instead of from thecontainer
argument.fps (int, float, World) – frames per second. Can also use a
World
instance if that instance’sfakeFrameRate
property has been set.codec (str) – four characters that specify the FOURCC code of the codec to use. The default ‘mp4v’ is a reasonably safe cross-platform/out-of-the-box option, especially with the .avi container format. But, as with all things OpenCV, and indeed all things video-codec-related, your mileage may vary considerably. Note that ‘mp4v’ is a lossy codec. For lossless compression (and hence perfectly accurate reconstruction of your stimuli) you may need to install a third-party codec—this seems to be quite a technical task so we can’t go into detail here.
container (str) – file extension dictating the default video container format (used only if there is no file extension in
filename
).
- WriteFrame(frame)
The
frame
argument can be anumpy
array, height x width x channels, of uint8 pixel values. The number of channels should be either 3 (RGB) or 4 (RGBA). The alpha channel, if any, will be ignored.Alternatively,
frame
can be aStimulus
orWorld
instance, in which case itsCapture()
method is called automatically.Note that, once the first frame is written, you should ensure that all subsequent frames have the same dimensions as the first.
- Shady.Utilities.WorldConstructorCommandLine(argv=None, doc=None, **defaults)
This tool is used in our example scripts, and may be useful to you in any applications you write that are similarly launched from the command line. It creates a general-purpose
CommandLine
object, but then pre-configures various options to match the main arguments that can be passed to theWorld
object constructor.Example:
'Welcome to foo.py' import Shady cmdline = Shady.WorldConstructorCommandLine( canvas=True ) # Add your own custom command-line option definitions here: hello = cmdline.Option( 'hello', default=False, type=bool, container=None ) cmdline.Help().Finalize() world = Shady.World( **cmdline.opts ) if hello: import Shady.Text greeting = world.Stimulus( text='Hello World!' ) world.Run()
In the above example, most of the
World
constructor arguments now have counterparts that can be passed on the command-line when you runfoo.py
. For example, if you saypython foo.py --screen=2
then theWorld
will be opened on your second screen. If you saypython foo.py --help
then (thanks to theHelp()
call above) the command-line arguments will be printed and then Python will exit without creating theWorld
. The command-line arguments all have the same default values as their counterparts in theWorld
constructor prototype, with one exception:canvas
has had its default value explicitly changed toTrue
.In the particular cases of
width
and/orheight
, they can be passed as named arguments (say,python foo.py --width=1920 --height=1080
) or as positional arguments (python foo.py 1920 1080
)If the
doc
argument is left asNone
, this function will impolitely ransack the calling namespace for a__doc__
variable, and use that if it finds it. Passdoc=''
to suppress this.