<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<?xml-stylesheet href="./_c74_ref.xsl" type="text/xsl"?>

<c74object name="ambicontrol" module="ICST Ambisonics">

    <digest>
		Trajectory controller for ambimonitor.
    </digest>

    <description>
		<p>Ambicontrol algorithmically controls points that exist inside an <m>ambimonitor</m> object. A connection to an <m>ambimonitor</m> is established by setting the "connect" attribute to the scripting name of the monitor. Methods include rotation random movements, constrained in bounding volumes, and recording/playing back trajectories from mouse movement or external algorithms.</p>
    </description>

    <!--METADATA-->
    <metadatalist>
	<metadata name="author">ICST | Zurich University of the Arts</metadata>
	<metadata name="tag">ICST Ambisonics</metadata>
	<metadata name="copyright">
	 © 2003 - 2021 ICST | Zurich University of the Arts
	</metadata>
	<metadata name="version">
	3.0 (Build 02/2021)
	</metadata>
    </metadatalist>

    <!--DISCUSSION-->
    <discussion>

    </discussion>

    <!--INLETS-->
    <!--do not use-->
    <inletlist>
    </inletlist>

    <!--OUTLETS-->
    <!--do not use-->
    <outletlist>
    </outletlist>

    <!--ARGUMENTS-->
    <objarglist>
    </objarglist>

    <!--MESSAGES-->
    <methodlist>
		
		<method name="bang">
		    <description>
				<p>Schedule next clock tick, output local point, execute control method:  <m>rotate</m>, <m>random</m>, <m>hrandom</m>, <m>vrandom</m>, <m>crandom</m>, <m>trajectory</m> - increment time.</p>
			</description>
		</method>
		
		<method name="int">
		    <description>
				<p>Set active attribute to on or off (0/1), starting or stopping animation.</p>
			</description>
		</method>
		
		<method name="float">
		    <description>
				<p>Set control's animation stepsize attribute (default: 1).</p>
			</description>
		</method>
		
		<method name="start">
		    <description>
				<p>Starting animation.</p>
			</description>
		</method>
		
		<method name="stop">
		    <description>
				<p>Stopping animation.</p>
			</description>
		</method>
			
		
		<method name="aed">
		    <description>
				<p>Input ambipoint with cartesian/rectangular coordinates to set centre point, or trajectory breakpoint when recording is active.</p>
				Format of polar/spherical ambipoint:<br/> 
				<code>"aed" &#60;point-ID&#62;&#60;azimuth&#62;&#60;elevation&#62;&#60;distance&#62;[&#60;group-ID&#62;&#60;yaw&#62;&#60;pitch&#62;&#60;roll&#62;]:optional</code>
		    </description>
		</method>
	
		<method name="xyz">
		    <description>
				<p>Input ambipoint with polar/spherical coordinates to set centre point, or trajectory breakpoint when recording is active</p>
				Format of cartesian/rectangular ambipoint:<br/> 
				<code>"xyz" &#60;point-ID&#62;&#60;x-value&#62;&#60;y-value&#62;&#60;z-value&#62;[&#60;group-ID&#62;&#60;yaw&#62;&#60;pitch&#62;&#60;roll&#62;]:optional</code>
			</description>
		</method>
		
		<method name="anything">
		    <description>
				<p>Select control method.</p>
				<p>Options are:</p>
				<ul>
					<li>nil: switch off any method</li>
					<li>rotate: switch to rotate method</li>
					<li>random: switch to random method &#8212;  movements in all directions</li>
					<li>hrandom: switch to hrandom method &#8212;  horizontal random, no movement in direction of the z axis</li>
					<li>vrandom: switch to vrandom method &#8212;  vertical random, movement in direction of the z axis only</li>
					<li>crandom: switch to crandom method &#8212;  circular random, random movement on a circular trajectory</li>
					<li>trajectory: switch to trajectory method</li>
				</ul>
		    </description>
		</method>	
		
		
		<method name="stability">
		    <description>
				<p>Random methods take additional stability message: time in ms to keep moving in one
direction and/or at the same speed.</p>
			</description>
		</method>		
		
		<method name="time">
		    <description>
				<p>Move trajectory point manually:</p>
				<p><m>int</m> original time in ms.</p>
				<p><m>float</m> fraction of the trajectory.</p>
			</description>
		</method>				
		
		<method name="record">
		    <description>
				<p>Sets ambicontrol into trajectory recording mode.</p>
				<p><m>record</m> with <m>int</m> argument, enables drawing a trajectory by dragging point with given index.</p>
			</description>
		</method>				
	
		<method name="close">
		    <description>
				<p>Finalise trajectory recording.</p>
			</description>
		</method>		
		
		<method name="clear">
		    <description>
				<p>Delete trajectory.</p>
			</description>
		</method>
		
		<method name="fit_trajectory">
		    <description>
				<p>Scale trajectory to bounding box, retaining shape (works only if bounding volume is of type box).</p>
			</description>
		</method>
		
		<method name="store">
		    <description>
				<p>Store trajectory &#8212; argument <m>symbol</m>: name of trajectory</p>
			</description>
		</method>		
		
		<method name="recall">
		    <description>
				<p>Recall trajectory &#8212; argument <m>symbol</m>: name of trajectory</p>
			</description>
		</method>		

		<method name="remove">
		    <description>
				<p>Remove trajectory &#8212; argument <m>symbol</m>: name of trajectory</p>
			</description>
		</method>
		
		<method name="remove_all">
		    <description>
				<p>Remove all trajectories</p>
			</description>
		</method>
		
		<method name="read">
		    <description>
				<p>Read trajectories from a file.</p>
			</description>
		</method>
	
		<method name="write">
		    <description>
				<p>Write trajectories to a file.</p>
			</description>
		</method>				
		
		<method name="dump_trajectories">
		    <description>
				Output all necessary messages from 3rd outlet in order to fill a trajectory selection <m>umenu</m>.		
			</description>
		</method>
		
		<method name="dump_current_trajectory">
		    <description>
				Output all breakpoints of current trajectory to 2nd outlet.	
			</description>
		</method>		

	
		<method name="version">
		    <description>
				Print version information to Max' console window.
		    </description>
		</method>
		<method name="report">
		    <description>
				Print internal state report Max' console window.
		    </description>
		</method>
	
    </methodlist>

    <!--ATTRIBUTES-->
    <attributelist>
		
	<attribute name="active" get="0" set="0" type="onoff" size="1" value="Active">
		<description>
		<p>Activate/deactivate animation (default: off)</p>
		</description>
	</attribute>
	
	<attribute name="point_size" get="0" set="0" type="symbol" size="1" value="Connected Ambimonitor">
	    <description>
			Connected <m>ambimonitor</m>'s scripting name (default: "").
	    </description>
	</attribute>
	
	<attribute name="method" get="0" set="0" type="symbol" size="1" value="Control Method">
	    <description>
			Set control method (default: 'nil').
			<ul>
				<li>nil: switch off any method</li>
				<li>rotate: switch to rotate method</li>
				<li>random: switch to random method &#8212;  movements in all directions</li>
				<li>hrandom: switch to hrandom method &#8212;  horizontal random, no movement in direction of the z axis</li>
				<li>vrandom: switch to vrandom method &#8212;  vertical random, movement in direction of the z axis only</li>
				<li>crandom: switch to crandom method &#8212;  circular random, random movement on a circular trajectory</li>
				<li>trajectory: switch to trajectory method</li>
			</ul>
	    </description>
	</attribute>

	<attribute name="points" get="0" set="0" type="int" size="variable number of" value="Point Indices">
	    <description>
			<p> Point indices to control.</p>
	    </description>
	</attribute>
	
	<attribute name="groups" get="0" set="0" type="int" size="variable number of" value="Group Indices">
	    <description>
			<p>Group indices to control.</p>
	    </description>
	</attribute>
	
	<attribute name="stepsize" get="0" set="0" type="float" size="1" value="Stepsize">
	    <description>
			<p>Stepsize for animation.(default:1).</p>
			<p>Example values: 2 = double speed, 1 = real time, 0.5 = half speed</p>
	    </description>
	</attribute>
	
	<attribute name="interval" get="0" set="0" type="int" size="1" value="Interval">
	    <description>
			Self-clocking interval in ms (default 100).
	    </description>
	</attribute>
	
	<attribute name="loop" get="0" set="0" type="int" size="1" value="Loop mode">
	    <description>
			Trajectory loop mode (default: 'off').
			<ul>
				<li>0: off &#8212; switch looping</li>
				<li>1: circular &#8212; at end, jump to start</li>
				<li>2: palindrome &#8212; at start/end, reverse direction</li>
			</ul>
	    </description>
	</attribute>
	
	<attribute name="interpolation" get="0" set="0" type="int" size="1" value="Interpolation mode">
	    <description>
			Trajectory interpolation mode (default: 'off').
			<ul>
				<li>0: off &#8212; switch looping</li>
				<li>1: linear &#8212; interpolate in rectangular coordinates</li>
				<li>2: polar &#8212; interpolate in spherical coordinates</li>
			</ul>
	    </description>
	</attribute>
	
	<attribute name="index" get="0" set="0" type="int" size="1" value="Coordinate Input Index">
	    <description>
			Coordinate input index (default: 0).
	    </description>
	</attribute>
	
	<attribute name="pointsize" get="0" set="0" type="float" size="1" value="Pointsize">
	    <description>
			Display point size (default: 8.0).
	    </description>
	</attribute>

	<attribute name="show_volume" get="0" set="0" type="onoff" size="1" value="Show Bounding Volume">
	    <description>
			Activate/deactivate displaying the bounding volume (default: on).
	    </description>
	</attribute>
	
	<attribute name="volume_type" get="0" set="0" type="int" size="1" value="Interpolation mode">
	    <description>
			Bounding volume type (default: 'box').
			<ul>
				<li>0: box &#8212; switch looping</li>
				<li>1: pie slice &#8212; rectangular bounding box</li>
				<li>2: polar &#8212; spherical slice (azimuth, aperture, height</li>
			</ul>
	    </description>
	</attribute>
	
	<attribute name="volume" get="0" set="0" type="float" size="3" value="Bounding Volume Parameters">
	    <description>
			<p>Bounding volume parameters (default: 2.0 2.0 2.0).</p>
			<p><m>box</m>: width (x) depth (y) height (z)</p>
			<p><m>pie slice</m>: azimuth (angle), aperture (angle), height</p>
	    </description>
	</attribute>
		
	
	<attribute name="trajectory_color" get="0" set="0" type="rgba" size="1" value="Trajectory Line Color">
	    <description>
			<p>Trajectory line color (default: 1. 1. 1. 0.25)</p>
	    </description>
	</attribute>	
	
	<attribute name="trajectory_point_color" get="0" set="0" type="rgba" size="1" value="Trajectory Point Color">
	    <description>
			<p>Trajectory point color (default: 1.0 1.0 1.0 0.5)</p>
	    </description>
	</attribute>		
	
	<attribute name="volume_color" get="0" set="0" type="rgba" size="1" value="Bounding Volume Color">
	    <description>
			<p>Bounding volume color (default: 0.0 0.0 0.0 0.8)</p>
	    </description>
	</attribute>		
	

    </attributelist>
	
	<!-- Inlets/Uutlets-->
    <misc name = "Input">
	<entry name ="Inlet 1 [bang, int, float, list, anything]">
	    <description>
		Coordinates, controls, messages.
	    </description>
	</entry>
    </misc>

    <misc name = "Output">
	<entry name ="Outlet 1 [list]">
	    <description>
			<p>Aed coordinates of local centre point:</p> 
			<code>"aed" &#60;point-ID&#62;&#60;azimuth&#62;&#60;elevation&#62;&#60;distance&#62;[&#60;group-ID&#62;&#60;yaw&#62;&#60;pitch&#62;&#60;roll&#62;]:optional</code>
	    </description>
	</entry>
	<entry name ="Outlet 2 [list]">
	    <description>
			<p>Trajectory menu etc.</p> 
	    </description>
	</entry>
	
    </misc>

    <misc name = "Discussion">
	<entry name ="Keywords">
	    <description>
		ambicontrol, algorithms, control, rotation, random, trajectory, bounding box
	    </description>
	</entry>
    </misc>
	
    <!--SEEALSO-->
	<seealsolist>	
		<seealso name="ambimonitor"/>
		<!-- <seealso name="ambicontrol"/> -->
		<seealso name="ambipoint"/>
		
		<seealso name="icst.map"/>
		<seealso name="icst.random"/>
		<seealso name="icst.spline"/>
		
		<seealso name="icst.button"/>
		<seealso name="icst.intui"/>
		<seealso name="icst.floatui"/>
		<seealso name="icst.listui"/>

		<seealso name="ambiencode~"/>
		<seealso name="ambidecode~"/>
		<seealso name="ambipanning~"/>
				
		<seealso name="mc.ambiencode~"/>
		<seealso name="mc.ambidecode~"/>
		<seealso name="mc.ambipanning~"/>
	</seealsolist>

</c74object>
