MaxPatch¶

Instantiation¶

class maxpy.MaxPatch(template=None, load_file=None, reorder=True, verbose=True)¶

This class represents a MaxMSP patch. A MaxPatch can be created as a copy of a template file, or by loading in an existing .maxpat file.

Parameters

template (str, optional; default: None) – the path to a template .maxpat file. Can be given as an absolute path, a relative path from the current directory, or a relative path from MaxPy/maxpy/data/PATCH_TEMPLATES/.
load_file (str, optional; default: None) – the path to an existing .maxpat file to be loaded in. Can be given as an absolute path or a relative path from the current directory.
reorder (bool, optional; default: True) – whether or not to reassign object ids after loading in an existing file. See MaxPatch.reorder().
verbose (bool, optional; default: True) – for logging output.

Notes:

If load_file is given, template will be ignored. If neither files are given, a default empty MaxPatch will be created.

To load in abstractions or js objects, the linked files must be in the current directory.

To load in a patch with external package objects, the packages should first be imported.

Unknown objects will retain patchcord connections when loaded in, but cannot be edited. They can be replaced with known objects via MaxPatch.replace().

Examples:

Creating an empty patch:

>>> empty_patch = maxpy.MaxPatch()
Patcher: new patch created from template file: empty_template.json

Loading in a patch containing a button connected to a counter:

>>> loaded_patch = maxpy.MaxPatch(load_file='my_patch.maxpat', verbose=True)
Patcher: loading patch from existing file: my_patch.maxpat
Patcher: button added, total objects 1
Patcher: counter added, total objects 2
Patcher: connected: ( button : outlet 0 ---> counter : inlet 0 )
Patcher: patch loaded from existing file: my_patch.maxpat

Properties¶

property MaxPatch.objs: dict¶: A dictionary of all Max objects in the patch, stored by object id. Read-only.

property MaxPatch.num_objs: int¶: The number of Max objects in the patch. Read-only.

property MaxPatch.curr_position: list[int, float]¶: The current position of the ‘cursor’ at which to place Max objects. Given as a two-element list [x, y] of patch coordinates. Can be set using MaxPatch.set_position().

property MaxPatch.dict: dict¶: The JSON dict of the patch. Read-only.

Example:

>>> loaded_patch.objs
{'obj-1': button [button], 'obj-2': counter [counter]}
>>> loaded_patch.num_objs
2
>>> loaded_patch.curr_position
[0.0, 0.0]
>>> loaded_patch.dict
{
'patcher':
        {
        'fileversion': 1,
        ...
        'boxes': [ ... ],
        'lines': [ ... ],
        'dependency_cache': [],
        'autosave': 0
        }
}

Functions¶

MaxPatch.check(*flags)¶

This method checks the patch for linked abstractions, unknown objects, and linked/unlinked js objects.

Parameters: *flags (str, optional) – takes keywords 'abstractions', 'unknowns', 'js'. If no flags given, checks all three categories.
Returns: outputs a list of all the objects that fall under the specified categories, identified by object id, name, text, and linked file (if applicable).
Return type: printed output

Notes:

See Linked Files, Unknown Objects.

Example:

>>> patch.objs
{'obj-1': not-an-obj [not-an-obj],
'obj-2': existing-abstraction [existing-abstraction],
'obj-3': js [js 5 4 existing.js],
'obj-4': js [js not-a-file.js]}
>>> patch.check()
PatchCheck: unknown objects :
   obj-1 : not-an-obj [not-an-obj]
PatchCheck: unlinked js objects :
   obj-4 : js [js not-a-file.js]
PatchCheck: linked js objects (files must be in same folder as patch file):
   obj-3 : js [js 5 4 existing.js] --> existing.js
PatchCheck: linked abstractions (files must be in same folder as patch file):
   obj-2 : existing-abstraction [existing-abstraction] --> existing-abstraction.maxpat

MaxPatch.connect(*connections, verbose=True)¶

This method creates patchcords to connect objects. currently fixing connection specification…

Parameters

*connections – a list of connections to make. Each connection must be specified as a tuple (Outlet, Inlet (, list)). The optional third element specifies midpoints (curves) of the patchcord as a list of [x, y] coordinates.
verbose (bool, optional; default: True) – for logging output.

Returns

None.

Notes:

The current scheme for specifying connections is somewhat clunky (see example below).

This will be fixed at some point…

Example:

>>> patch.objs

MaxPatch.delete(objs=None, cords=None, verbose=True)¶

Delete objects and/or patchcords. Deleting objects will automatically delete any patchcords attached to them.

objs –> list of string “obj-num” objects to delete

cords –> list of connections (Outlet, Inlet)

MaxPatch.inspect(*objs, info='all')¶

Get desired information about specified objects.

objs –> list of objs to get info about, as strings “obj-num”

if objs=”all”, print info for each object

info –> desired info to print out

“all”: print all info below

“canvas”: print obj-num, position, connections to each inlet/outlet

“attributes”: print current settings of all available attributes

“common-box”: print current settings of common box attributes, if applicable

“obj-attribs”: print current settings of obj-specific attributes, if applicable

“connections”: print connections to each inlet/outlet

“position”: print position on canvas

MaxPatch.place(*objs, randpick=False, num_objs=None, seed=None, weights=None, spacing_type='grid', spacing=[80.0, 80.0], starting_pos=None, verbose=False)¶

Place objects in the patch.

objs –> list of object names as strings, OR list of objects as prev. created MaxObjects (or mix of both)

randpick –> True: pick n random objs from objs list (default pick 1)

num_objs –> integer: n = num_objs

num_objs –> list: give error & take first element on list

num_objs –> None: n = len(objs)

randpick –> False: pick all objs on objs list (default each picked once)

num_objs –> integer: each obj multiplied by num_objs

num_objs –> list: each objs multiplied by corresponding num_objs entry

num_objs –> None: n = len(objs)

seed –> random seed for picking/placing objs, if None then random seed

weights –> weight probabilities for picking objs, if None then equal probability

spacing_type –> options for how to place objs on canvas

“grid”: objects centered on a grid
- spacing –> tuple/list length 2: [x, y] grid spacings
“random”: random locations, using same seed as before (overlaps possible)
- spacing –> N/A
“custom”: location specified for each object
- spacing –> list: positions [[x, y]], can only be used for num_objs=1
“vertical”: objects stacked vertically
- spacing –> number: specify height

starting_pos –> starting position to place from, must be tuple/list length 2: [x, y]

verbose –> print output for seed, etc.

MaxPatch.reorder(verbose=False)¶: Re-number objects in patch, starting from 1.

MaxPatch.replace(curr_obj_num: str, new_obj, retain=True, verbose=False, **new_attribs)¶

Replace an object in the patch with a different object.

The new object can be specified as a string, or by reference to a MaxObject. Attributes in common (i.e. common box attribs) between old/new objects can be retained (will automatically retain). Additional attribute settings will override retained attributes. Patchcords will automatically be retained if possible, starting from xlet 0.

curr_obj_num –> id number in ‘obj-num’ string format of current object to be replaced new_obj –> either string specification or MaxObject of new object retain –> retain all attributes in common between old/new objects verbose –> log to console new_attribs –> any new attributes to give to the new object

MaxPatch.save(filename='default.maxpat', verbose=True, check=True)¶

Save to .maxpat file.

Usage: filename –> savefile name verbose –> print log message to console check –> run check_patch before saving

MaxPatch.set_position(new_x, new_y, from_place=False, verbose=False)¶

Set the current “cursor” position from which objects will be placed.

Must be formatted as [x, y] tuple or int of length 2.