[PD-announce] Pd FLOSS Manual Update pt 2

So here is part two!

The following chapters were newly created during the Book Sprint. We'd really like to see them come together, but we don't think they will be anywhere near ready before we decide to publish the version 1.0. Futher work on these chapters is also appreciated, but only after the chapters we have marked for inclusion in the 1.0 are complete. Writing, editing and proofreading on these chapters can continue as normal, and when we are ready for a second release (now with GEM + SENSORS!) then we will include them.

CHAPTERS FOR FURTHER DEVELOPMENT, not to be included in upcoming 1.0 release:

GEM SENSORS MIDI NETWORK DATA

When the version 1.0 is completed, and these chapters are also fixed, then we can consider a paper publication!!!!!!

Here are the issues and places for improvement on each chapter. Again, we welcome improvements to these chapters, but if you are going to spend any time on this manual in the next few weeks, it would make more sense to focus on the chapters marked for publication (see Part 1 of this update):

____GEM_____

-> These chapters need a lot of work to be anywhere near complete!

-> My suggestion is to do more tutorial-based stuff, like "how to" sections, rather than break down the material by taxonomy (which is how it is already documented elsewhere). Thus, "How to VJ with Images and Video using GEM" and "How to Create 3D Animations using GEM" would be preferable to existing system.

-> Perhaps rather than single GEM heading, each of these could be section heading with chapters beneath them? In such a case, the chapters beneath each section should follow some logical progression from one to the other, leading towards the goal of VJing or doing animations.

-> Also some of the examples are far too complex, and rely on arcane systems like [import] or objects with severe nameclashes like [counter] which are traps for new users and should be avoided!

* http://en.flossmanuals.net/bin/view/PureData/GEMIntroduction --Check for tone, perhaps more introduction and less credits, explain basic parts better (i.e. "2D and 3D graphics and animation, realtime image and video processing, and particles") --Show screenshot of help patches + examples in Pd Browser?

* http://en.flossmanuals.net/bin/view/PureData/GEMBasics --Mention "Red Book" and other technical OpenGL info later, it's not needed in beginners introduction, skip immediately to rendering --Re: [gemwin] question in text ("is this true?"): please verify this information or cut it! --In general, would be good to concentrate on doing things rather than exhaustively explaining technical details --Re: [pix] objects.... save this for chapter on it. --Perhaps what is needed here is overview of GEM functions, and then each chapter can deal with them independently as part of unified tutorials (VJing/Animation) --Section (or new chapter) on setting up second screen for live performance for each OS!

* http://en.flossmanuals.net/bin/view/PureData/GEMImagesMoviesAndVideo --This could really use less of reprinting helppatches, and more how to do things, like: ____Using [metro]/[float] counter to drive frame playback (changing playback speed or going backwards) ____Using [mod] and [+] to create smaller loops within film ____Use [random] to "granulate" film ____Use pix effects (where to insert in gemlist)(then refer to later chapter for more details, or work into single VJ tutorial as suggested above) --Section on video formats for each OS is essential!!!!

* http://en.flossmanuals.net/bin/view/PureData/GEMVideoMixer --I would like to see [alpha] plus [colorRGB] used in how to do simple crossfader instead of [pix_mix]. --Explanations could be helped more towards clarity. --Re: recommendation to "create abstractions": either explain this inline or direct reader to Patch Management section (to be created) which will cover subpatches, abstractions, etc --Webcam: needs Linux info on getting video devices in, there are probably other flags which need to be shown as well

* http://en.flossmanuals.net/bin/view/PureData/GEMPixEffects --Please don't use a PiDiP object [colorgrid] in a GEM tutorial!!!!!!! (Also not cross platform!) --Can this tutorial be done without need to import? (i.e. used normal counter instead of external?) I really don't agree with using objects that have such bad name clash issues, like [counter] --The [send] and [receive] are abbreviated (first bad) and not explained in tutorial (second bad) --In general, examples are too complex, please simplify!!!!!!!!!

* http://en.flossmanuals.net/bin/view/PureData/GEMSavingAndRecording --Same problem as above, please don't [import] as it makes it much more complicated to explain whole patch. Basic objects available in Pd-Extended are assumed, anything else should either be skipped or extensively explained in line! --While the toggle for turning gemwin on and off is useful, it is not explained in line and in general adds unneeded complexity to example patch. please simplify! --If this section is about [pix_record] then it would be best to focus on that object and leave fancy stuff out

* http://en.flossmanuals.net/bin/view/PureData/GEMScreens --Good place for second screen tutorial? --Per OS instructions with screenshots please!

* http://en.flossmanuals.net/bin/view/PureData/GEMBlueGreenScreen --Nothing there

* http://en.flossmanuals.net/bin/view/PureData/GEMVideoTracking --Good start but nowhere near complete. need to see more screenshots of video tracking at work, more real world examples --I think list at the end is far far far too ambitious for beginner's manual! (pattern recognition (TUIO), pix_opencv (face recognition), blobs and multiblobs, IR illumination and multitouch technology)

* http://en.flossmanuals.net/bin/view/PureData/GEMText --Nothing there

* http://en.flossmanuals.net/bin/view/PureData/GEMInteraction --Nothing there

* http://en.flossmanuals.net/bin/view/PureData/GEMFrameBuffer --Nothing there

* http://en.flossmanuals.net/bin/view/PureData/GEMGLSLShaders --Not much there, and I really consider this far too advanced for a beginners manual. This chapter should be sidelined until absolutely every other topic in GEM has been well covered.

* http://en.flossmanuals.net/bin/view/PureData/GEMdShapes --Nothing there --Suggest to merge shapes and animations and some others into general chapter on how to do animation in GEM

* http://en.flossmanuals.net/bin/view/PureData/GEMdAnimation --Nothing there --See GEMdShapes notes

* http://en.flossmanuals.net/bin/view/PureData/GEMCamera --Nothing there --Low priority for now --See GEMdShapes notes

* http://en.flossmanuals.net/bin/view/PureData/GEMLightingFogAmbientColor --Nothing there --Low priority for now --See GEMdShapes notes

http://en.flossmanuals.net/bin/view/PureData/GEMParticleSystems --Nothing there --Low priority for now --See GEMdShapes notes

____SENSORS____

-> Suggest renaming chapter to external inputs, and including MIDI, [key] etc

* http://en.flossmanuals.net/bin/view/PureData/GameControllers --The [cursor] object has nameclash!!!!!! Which lib? Please avoid libs which need [import] or have nameclash! --Would it be possible to simply open [hid] help file to start with, then explain furhter down how to code it from scratch? --The "minia" HID device is rather obscure hardware which most people will never have. Possibly move it + finished controller shown to some later section that shows people's custom controllers projects, rather than use as example --This chapter could use some better attention, clearer explanations, a "how to" 1, 2, 3 rather than current structure. For example, how to plug in Wingman and control very simple synth!

* http://en.flossmanuals.net/bin/view/PureData/Pduino --Good start, but needs work clarifying. --Section on installing the Pduino library needed for each OS --Section on installing Arduino needed for each OS --Section on getting USB serial emulation needed for each OS --Screenshot of "open button" should include submenus --One screenshot uses [pd display values without pegging the CPU] subpatch, which is not explained nor made available. Please avoid this, or explicitly have them open the [pduino] abstraction --Please make circuit diagram and spend some time explaining the circuit (i.e. tell what voltage divider is and how it works) --Re: [autoscale]: what lib is this? Is it in Pd-Extended by default or must it be imported. In general, it would be nice to use some basic maths there instead for simplicity, since we can't assume reader knows what [autoscale] will do. --Best to explain patches in-line as well as in patch comments. In-line text can be text-searched in browser or PDF reader, while comments in images cannot. --Perhaps also better explanation of [send] and [receive], or direct reader to chapter on it.

____MIDI____

* http://en.flossmanuals.net/bin/view/PureData/UsingMidi --This chapter needs some serious work. Again, there is more taxonomy here than tutorial. --I would like to see following: ____Intro to MIDI hardware ____How to set up system for each OS (See Configuring PD chapter) ____Tutorial showing how to plug in keyboard and get notes from proper channel ____Tutorial on how to plug in fader box and get CC info on proper channels ____Tutorial on how to send MIDI from Pd to other apps (FLOSS apps, if possible)(using IAC bus on OSX, MidiOx or similar on Windows and QJackCTL on Linux) --The "pd uc16" example screenshot is needlessly complicated, and graphical bangs like that should be discouraged as they would cause audio glitches on many users' systems if data came in quick enough

____NETWORK DATA____

* http://en.flossmanuals.net/bin/view/PureData/Receive --Needs a lot of work!!!! --Please real world examples rather than taxonomy

* http://en.flossmanuals.net/bin/view/PureData/OSC --Please use built in OSC as default, since those are what comes out of the box in Pd Extended, are the simplest and also still the most widely used --If you want to use mrpeach objects, please do this in a separate section or chapter (Advanced OSC, perhaps?) and please be sure to explain in-line how to load non-standard externals (see Configuring Pd chapter, perhaps best to put it there are reference it)

Thanks again to everyone who helped out over the weekend, and let's all get busy making this manual the best it can be.

Best wishes from Berlin! Derek