الصفحة الرئيسية>المتعلقة بالبرمجة>شفرة المصدر الأخرى
تنزيل

py2max

مكتبة python3 خالصة بدون تبعيات تهدف إلى تسهيل إنشاء ملفات Max patcher دون الاتصال بالإنترنت ( .maxpat ، .maxhelp ، .rbnopat ).

إذا كنت تبحث عن عناصر خارجية لـ python3 لـ Max/MSP، فراجع مشروع py-js.

سمات

  • إنشاء ملفات Max patcher دون اتصال بالإنترنت باستخدام كائنات Python، المقابلة، على أساس واحد لواحد، مع كائنات Max/MSP المخزنة في تنسيق الملف المستند إلى .maxpat JSON.

  • تحويل ذهابًا وإيابًا بين ملفات (JSON) .maxpat بمستويات عشوائية من التداخل وكائنات Patcher و Box و Patchline Python المقابلة.

  • من المحتمل أن يتعامل مع أي كائن Max أو maxclass.

  • الكثير من اختبارات الوحدة، تغطية بنسبة 99% تقريبًا.

  • التحليل والتعديل النصي دون الاتصال بالإنترنت لتصحيحات Max من حيث التركيب والبنية (مثل الرسوم البيانية للكائنات) وخصائص الكائن والتخطيط (باستخدام خوارزميات رسم الرسم البياني).

  • يسمح بالتخطيط والتكوين الدقيق لكائنات Max.

  • تحتوي كائنات Patcher على طرق عامة مثل add_textbox ويمكن أن تحتوي أيضًا على طرق متخصصة مثل add_coll . على سبيل المثال، تحتوي هذه الطريقة على وسيطة dictionary لتسهيل تعبئة كائن coll مسبقًا (راجع py2max/tests/test_coll.py ).

  • يوفر ميزة maxclassdb التي تستدعي التكوينات الافتراضية لـ Max Objects.

حالات الاستخدام الممكنة

  • إنشاء ملف patcher مكتوبًا.

  • تعديل دفعة من ملفات .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' )

مثال آخر مع subpatchers: 

 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 تقريبًا إلى ملف patcher باستخدام .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 الاختبار إذا لم يتم تثبيت الحزم المطلوبة، لذا فهذه اختبارات اختيارية تمامًا.

إذا كنت تصر على الغوص في حفرة الأرانب، وترغب في إجراء جميع الاختبارات، فستحتاج إلى الحزم التالية (وتوابعها):

  • Networkx: pip install networkx
  • matplotlib: pip install matplotlib
  • pygraphviz: يتطلب Pygraphviz تثبيت مكتبة تطوير graphviz: https://www.graphviz.org/ (في نظام التشغيل macOS يمكن القيام بذلك عبر brew install graphviz ) - ثم يمكنك pip install pygraphviz
  • Adaptagrams: قم أولاً ببناء Adaptagrams C++ Libs ثم قم ببناء غلاف python المستند إلى swig.
  • pyhola: غلاف pybind11 للمخططات التكيفية. اتبع تعليمات البناء في الملف التمهيدي (README) وقم بالتثبيت من git repo.
  • tsmpy: التثبيت من git repo
  • الرسم المتعامد: التثبيت من git repo

المحاذير

  • لا تزال مستندات 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__ الداخلية الخاصة بها. في الواقع، هذه هي الطريقة التي يتم بها تنفيذ طريقة فئة patcher .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 : قارن باستخدام Deepdiff
  • coverage.sh : تشغيل تغطية pytest وإنشاء تقرير تغطية HTML

لاحظ أنه إذا كنت تريد إنشاء py2max كعجلة: 

pip install build
cd py2max
python3 -m build .

يجب أن تكون العجلة في دليل dist .

أمثلة على الاستخدام

  • إنشاء Max patchers لـ faust2rnbo

الفروع البديلة

فرع Pydantic2

يوجد فرع تجريبي لهذا المشروع وهو مبني على مشروع pydantic2.

يتمتع هذا البديل بالمزايا التالية:

  • يتتبع الفرع الرئيسي
  • اجتياز الاختبارات بنسبة 100%
  • المزيد من واجهة برمجة التطبيقات الثعبانية
  • تحسين التسلسل/إلغاء التسلسل
  • الاستخدام واسع النطاق للتحقق من صحة النوع بناءً على تلميحات النوع. 
 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 )]

فرع الخصائص

كان هناك جهد مبكر لتوفير الوصول إلى السمات المستندة إلى الخاصية وواجهة برمجة التطبيقات المحسنة. لقد تم استبداله بفرع pydantic2 ولن يتم تطويره أكثر.

الاعتمادات والترخيص

جميع الحقوق محفوظة للمؤلفين الأصليين:

  • ستيف كيفير، وتيم دواير، وكيم ماريوت، ومايكل ويبرو. HOLA: تخطيط الشبكة المتعامد الشبيه بالإنسان. في التصور ورسومات الكمبيوتر، معاملات IEEE، المجلد 22، العدد 1، الصفحات 349 - 358. IEEE، 2016. DOI

  • أريك أ. هاجبرج، ودانيال أ. شولت، وبيتر ج. سوارت، "استكشاف بنية الشبكة وديناميكياتها ووظيفتها باستخدام NetworkX"، في وقائع مؤتمر بايثون السابع للعلوم (SciPy2008)، وجايل فاروكو، وترافيس فوت، وجارود ميلمان (محرران)، (باسادينا، كاليفورنيا، الولايات المتحدة الأمريكية)، الصفحات من 11 إلى 15، أغسطس 2008

  • أسلوب لرسم الرسوم البيانية الموجهة Emden R. Gansner, Eleftherios Koutsofios, Stephen C. North, Kiem-phong Vo • IEEE TRANSACTIONS ON SOFTWARE ENGINEERING • تم النشر في عام 1993

  • غانسنر، إي آر، كورين، واي، نورث، إس. (2005). الرسم البياني عن طريق تخصص الإجهاد. في: Pach، J. (eds) الرسم البياني. GD 2004. ملاحظات محاضرة في علوم الكمبيوتر، المجلد 3383. سبرينغر، برلين، هايدلبرغ. https://doi.org/10.1007/978-3-540-31843-9_25

  • نظام تصور الرسم البياني المفتوح وتطبيقاته في هندسة البرمجيات Emden R. Gansner, Stephen C. North • البرمجيات - الممارسة والخبرة • تم النشر في عام 2000

يوسع
معلومات إضافية
تطبيقات ذات صلة
نوصي لك
أخبار ذات صلة الكل