py2max
1.0.0
Чистая библиотека Python3 без зависимостей, предназначенная для облегчения автономной генерации файлов патчей Max ( .maxpat , .maxhelp , .rbnopat ).
Если вы ищете внешние компоненты Python3 для Max/MSP, ознакомьтесь с проектом py-js.
Автономное создание файлов патчей Max по сценарию с использованием объектов Python, взаимно однозначно соответствующих объектам Max/MSP, хранящимся в формате файлов на основе .maxpat JSON.
Прямое преобразование между файлами (JSON) .maxpat с произвольными уровнями вложенности и соответствующими объектами Python Patcher , Box и Patchline .
Потенциально может обрабатывать любой объект Max или maxclass.
Множество модульных тестов, охват ~99%.
Анализ и автономная скриптовая модификация патчей Max с точки зрения состава, структуры (в виде графов объектов), свойств объектов и макета (с использованием алгоритмов рисования графов).
Обеспечивает точную компоновку и настройку объектов Max.
Объекты Patcher имеют общие методы, такие как add_textbox , а также могут иметь специализированные методы, такие как add_coll . Например, этот метод имеет аргумент- dictionary , который упрощает предварительное заполнение объекта coll (см. py2max/tests/test_coll.py ).
Предоставляет функцию maxclassdb , которая вызывает конфигурации Max Objects по умолчанию.
Создание скриптового файла патчера.
Пакетная модификация существующих файлов .maxpat.
Используйте богатую стандартную библиотеку и экосистему Python для создания параметризуемых объектов с конфигурацией из автономных источников. Например, уникальные генераторы волновых таблиц, сконфигурированные из случайных файлов волновых таблиц.
Генерация тестовых примеров и файлов .maxhelp во время внешней разработки.
Упрощает создание объектов с большим количеством параметров.
Предварительное заполнение объектов-контейнеров, таких как объекты coll , dict и table , данными.
Помогите сэкономить время на создании множества объектов с немного разными аргументами.
Используйте алгоритмы рисования/разметки графиков на сгенерированных патчах.
Генеративная генерация патчей (-;
и т. д..
p = Patcher ( 'my-patch.maxpat' )
osc1 = p . add_textbox ( 'cycle~ 440' )
gain = p . add_textbox ( 'gain~' )
dac = p . add_textbox ( 'ezdac~' )
osc1_gain = p . add_line ( osc1 , gain ) # osc1 outlet 0 -> gain inlet 0
gain_dac0 = p . add_line ( gain , dac , outlet = 0 , inlet = 0 )
gain_dac1 = p . add_line ( gain , dac , outlet = 0 , inlet = 1 )
p . save ()По умолчанию объекты возвращаются (включая линии исправлений), а выходы и входы линий исправлений установлены на 0. Хотя возвращенные объекты полезны для связывания, возвращенные линии исправлений — нет. Таким образом, более кратко сказанное выше можно записать так:
p = Patcher ( 'my-patch.maxpat' )
osc1 = p . add_textbox ( 'cycle~ 440' )
gain = p . add_textbox ( 'gain~' )
dac = p . add_textbox ( 'ezdac~' )
p . add_line ( osc1 , gain )
p . add_line ( gain , dac )
p . add_line ( gain , dac , inlet = 1 )
p . save () Со встроенными псевдонимами ( .add для методов типа .add_* и .link для .add_line ) приведенный выше пример можно записать в еще более сокращенной форме (и с вертикальной компоновкой) как:
p = Patcher ( 'out_vertical.maxpat' , layout = 'vertical' )
osc = p . add ( 'cycle~ 440' )
gain = p . add ( 'gain~' )
dac = p . add ( 'ezdac~' )
p . link ( osc , gain )
p . link ( gain , dac )
p . link ( gain , dac , 1 )
p . save () Кроме того, вы можете проанализировать существующие файлы .maxpat , изменить их и затем сохранить изменения:
p = Patcher . from_file ( 'example1.maxpat' )
# ... make some change
p . save_as ( 'example1_mod.maxpat' )Другой пример с субпатчерами:
p = Patcher ( 'out.maxpat' )
sbox = p . add_subpatcher ( 'p mysub' )
sp = sbox . subpatcher
in1 = sp . add ( 'inlet' )
gain = sp . add ( 'gain~' )
out1 = sp . add ( 'outlet' )
osc = p . add ( 'cycle~ 440' )
dac = p . add ( 'ezdac~' )
sp . link ( in1 , gain )
sp . link ( gain , out1 )
p . link ( osc , sbox )
p . link ( sbox , dac )
p . save () Обратите внимание, что классы Python по сути представляют собой простые оболочки вокруг структур JSON в файле .maxpat, и почти все объекты Max/MSP и Jitter могут быть добавлены в файл патчера с помощью .add_textbox или общих методов .add . Существуют также специализированные методы в форме .add_<type> для чисел, числовых параметров, субпаттеров и объектов типа контейнера (более подробную информацию см. в примечаниях к проектированию ниже).
Самый простой способ:
git https://github.com/shakfu/py2max.git
cd py2max
pip install . # optional Обратите внимание, что для использования py2max не требуется устанавливать его, поэтому вы можете пропустить pip install . часть, если хотите, просто cd в клонированный каталог и начните его использовать:
$ cd py2max
$ ipython
In [1]: from py2max import Patcher
In [2]: p = Patcher.from_file( " tests/data/simple.maxpat " )
In [3]: p._boxes
Out[3]: [Box(id= ' obj-2 ' , maxclass= ' ezdac~ ' ), Box(id= ' obj-1 ' , maxclass= ' newobj ' )] py2max имеет обширный набор тестов, тесты находятся в папке py2max/tests .
Все тесты можно запустить следующим образом:
pytest Результаты всех тестов будут выведены в папку outputs .
Обратите внимание, что некоторые тесты можно пропустить, если необходимый для теста пакет невозможно импортировать.
Проверить, какой тест пропущен, можно следующим образом:
pytest -vЧтобы проверить тестовое покрытие:
./scripts/coverage.shкоторый по сути делает следующее
mkdir -p outputs
pytest --cov-report html:outputs/_covhtml --cov=py2max testsЧтобы запустить индивидуальный тест:
python3 -m pytest tests.test_basic Обратите внимание: поскольку py2max в первую очередь занимается генерацией и манипулированием json , большинство тестов не имеют зависимостей, поскольку json уже встроен в stdlib.
Однако куча тестов исследует применение алгоритмов компоновки ортогональных графов и для этого использовалась целая куча пакетов, от широко известных до эзотерических.
Как упоминалось выше, pytest пропустит тест, если необходимые пакеты не установлены, поэтому это совершенно необязательные тесты.
Если вы настаиваете на погружении в кроличью нору и хотите запустить все тесты, вам понадобятся следующие пакеты (и их зависимости):
pip install networkxpip install matplotlibbrew install graphviz ) — затем вы можете pip install pygraphvizДокументы API по-прежнему недоступны.
Текущий алгоритм компоновки по умолчанию крайне элементарный, однако есть несколько многообещающих направлений, и вы также можете увидеть визуальное сравнение того, насколько хорошо работают разные алгоритмы компоновки в этом контексте.
Хотя генерация не использует объекты py2max, Max, к сожалению, не обновляется из файла, когда он открыт, поэтому вам придется продолжать закрывать и снова открывать Max, чтобы увидеть изменения в дереве объектов.
Для тех немногих объектов, которые имеют свои собственные методы, текущая реализация отличает объекты с тильдой от объектов без тильды, предоставляя другой метод с суффиксом _tilde :
gen = p . add_gen ()
gen_tilde = p . add_gen_tilde () Формат .maxpat JSON на самом деле довольно минимален и иерархичен. У него есть родительский Patcher и дочерние записи Box , а также Patchlines . Некоторые поля содержат другие экземпляры patcher для представления вложенных субпатчеров, gen~ патчей и т. д.
Приведенная выше структура напрямую соответствует реализации Python, которая состоит из трех классов: Patcher , Box и Patchline . Эти классы расширяются через соответствующие **kwds и внутренние структуры __dict__ . Фактически, именно так реализуется метод класса патчера .from_file .
Это оказывается наиболее удобным и гибким способом обработки всех различий между сотнями объектов Max, MSP и Jitter.
Растущий список методов исправлений был реализован для специализации и облегчения создания определенных классов объектов, требующих дополнительной настройки:
.add_attr.add_beap.add_bpatcher.add_codebox.add_coll.add_comment.add_dict.add_floatbox.add_floatparam.add_gen.add_intbox.add_intparam.add_itable.add_message.add_rnbo.add_subpatcher.add_table.add_textbox.add_umenu Это краткий список, но один только метод add_textbox может обрабатывать почти все случаи. Остальные нужны просто для удобства и для экономии набора текста.
Как правило, рекомендуется начинать использовать py2max с помощью этих методов add_<type> , поскольку большинство необходимых параметров встроены в методы, и вы можете получить поддержку завершения IDE. Как только вы освоитесь с параметрами, используйте общую сокращенную форму: add , которая требует меньше ввода, но компромиссом является потеря поддержки завершения параметров IDE.
В проекте есть несколько скриптов, которые могут быть полезны:
convert.py : преобразовать maxpat в yaml для удобства чтения во время разработки.compare.py : сравнение с помощью deepdiffcoverage.sh : запустить покрытие pytest и создать отчет о покрытии в формате HTML.Обратите внимание: если вы хотите построить py2max как колесо:
pip install build
cd py2max
python3 -m build . Тогда колесо должно находиться в каталоге dist .
Существует экспериментальная ветка этого проекта, основанная на проекте pydantic2.
Этот вариант имеет следующие преимущества:
In [ 1 ]: from py2max import Patcher
In [ 2 ]: p = Patcher ( path = 'outputs/demo.maxpat' )
In [ 3 ]: msg = p . add_message ( 'set' )
In [ 4 ]: p . boxes
Out [ 4 ]: [ Box ( id = 'obj-1' , text = 'set' , maxclass = 'message' , numinlets = 2 , numoutlets = 1 , outlettype = [ '' ], patching_rect = Rect ( x = 48.0 , y = 48.0 , w = 66.0 , h = 22.0 ), patcher = None )] Еще одно перспективное направление этого варианта — создание специализированных классов для объектов, имеющих свой уникальный maxclass . Итак, в этом случае вышеизложенное будет звучать так:
In [ 4 ]: p . boxes
Out [ 4 ]: [ Message ( id = 'obj-1' , text = 'set' , maxclass = 'message' , numinlets = 2 , numoutlets = 1 , outlettype = [ '' ], patching_rect = Rect ( x = 48.0 , y = 48.0 , w = 66.0 , h = 22.0 ), patcher = None )] На ранней стадии были предприняты попытки обеспечить доступ к атрибутам на основе свойств и улучшенный API. Он был заменен веткой pydantic2 и не будет развиваться дальше.
Все права принадлежат первоначальным авторам:
Стив Киффер, Тим Дуайер, Ким Марриотт и Майкл Уайброу. HOLA: человеческая ортогональная схема сети. В разделе «Визуализация и компьютерная графика», IEEE Transactions, том 22, выпуск 1, страницы 349–358. IEEE, 2016. DOI.
Арик А. Хагберг, Дэниел А. Шульт и Питер Дж. Сварт, «Изучение структуры, динамики и функций сети с использованием NetworkX», в материалах 7-й конференции «Python in Science Conference» (SciPy2008), Гэля Варокво, Трэвиса Воота и Джаррода Миллмана. (Ред.), (Пасадена, Калифорния, США), стр. 11–15, август 2008 г.
Техника рисования ориентированных графов Эмден Р. Ганснер, Элефтериос Кутсофиос, Стивен К. Норт, Ким-фонг Во • IEEE ТРАНЗАКЦИИ ПО ПРОГРАММНОЙ РАЗРАБОТКЕ • Опубликовано в 1993 г.
Ганснер, Э.Р., Корен, Ю., Норт, С. (2005). Построение графика методом мажорирования напряжений. В: Пах, Дж. (ред.) Рисование графиков. GD 2004. Конспекты лекций по информатике, том 3383. Springer, Берлин, Гейдельберг. https://doi.org/10.1007/978-3-540-31843-9_25
Система визуализации открытых графов и ее приложения в разработке программного обеспечения Эмден Р. Ганснер, Стивен К. Норт • ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ – ПРАКТИКА И ОПЫТ • Опубликовано в 2000 г.
