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

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

    <digest>
		GUI object for Ambisonic sound spatialisation.
    </digest>

    <description>
		<p>Ambimonitor provides a graphical user interface for manipulating sources and sinks in a spatial audio scene. It displays, outputs and stores points in the <m>ambipoint</m>-format, ready to be applied in the ICST Ambisonics audio-externals.</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="aed">
		    <description>
				Input ambipoint with cartesian/rectangular coordinates and output both polar and cartesian formats (incl. group-ID &amp; orientation).<br/><br/>
				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>
				Input ambipoint with polar/spherical coordinates and output both polar and cartesian formats (incl. group-ID &amp; orientation).<br/><br/>
				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="orientation">
		    <description>
				Input orientation values for a specific point and activate its orientation display and output.<br/><br/>
				Format :<br/> 
				<code>"orientation" &#60;point-ID&#62;&#60;yaw&#62;&#60;pitch&#62;&#60;roll&#62; </code>
				To deactivate a point's orientation display and output:<br/>
				<code>"orientation" &#60;point-ID&#62; "no"</code>
			</description>
		</method>
		
		<method name="set">
		    <description>
				Input ambipoint or orientation values without output.<br/><br/>
				Format :<br/> 
				<code>"set" "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>
				<code>"set"  "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>
				<code>"set" "orientation" &#60;point-ID&#62;&#60;yaw&#62;&#60;pitch&#62;&#60;roll&#62; </code>

			</description>
		</method>
		
		
		<method name="clear">
		    <description>
				Remove all points.
		    </description>
		</method>
		
		<method name="delete">
		    <description>
				Remove point(s) at given indices (if present). Arguments: one or several point-IDs &#60;ints&#62; 
		    </description>
		</method>

		<method name="rename">
		    <description>
				Rename point at given index (if present). Arguments: point-ID &#60;int&#62;; name &#60;symbol&#62; or &#60;int&#62;
		    </description>
		</method>
		
		<method name="group">
		    <description>
				Assign point at given index to given group (if present). Point index 0 assigns group to all points.
				<code>"group" &#60;group index&#62;&#60;point index 1&#62;...&#60;point index n&#62;</code>
		    </description>
		</method>
		
		<method name="dump">
		    <description>
				Outputs all points.
		    </description>
		</method>
	
	<method name="int">
	    <description>
			Recall snapshot at given slot (if present).
	    </description>
	</method>	

	<method name="anything">
	    <description>
			Recall snapshot with given name (symbol) if present.
	    </description>
	</method>		

	<method name="list">
	    <description>
			<p>2 Elements: recall snapshot and specify interpolation time as 2nd element.</p>
			<p>3 Elements: recall snapshot and specify interpolation mode as 3rd element (linear or polar interpolation).</p>
			
		</description>
	</method>
	
	<method name="store">
	    <description>
			Store snapshot at given index.
		</description>
	</method>
	
	<method name="remove">
	    <description>
			Remove snapshot at given index.
		</description>
	</method>
	
	<method name="remove_all">
	    <description>
			Remove all snapshots.
		</description>
	</method>
	
	<method name="zoom">
	    <description>
			<p>Set zoom factor and focal point simultaneously.</p>
			<code>&#60;zoom_factor&#62;&#60;focal_point.x&#62;&#60;focal_point.y&#62;&#60;focal_point.z&#62;</code>
		</description>
	</method>

	<method name="set_interpolation">
	    <description>
			<p>Associate time and mode with a specific snapshot.</p>
		</description>
	</method>
	
	<method name="xfade">
	    <description>
			<p>Manual interpolation.</p>
			<code>"xfade" &#60;snapshot 1&#62;&#60;snapshot 2&#62;&#60;xfade factor&#62;&#60;mode (optional)&#62;</code>
			
		</description>
	</method>	
	
	<method name="write">
	    <description>
			Write all stored snapshots to an xml-formatted file.		
		</description>
	</method>	

	<method name="read">
	    <description>
			Read snapshots from an xml-formatted file.		
		</description>
	</method>	
	
	
	<method name="dump_snapshots">
	    <description>
			Output all necessary messages from 3rd outlet in order to fill a snapshot selection <m>umenu</m>.		
		</description>
	</method>	
	
	<method name="version">
	    <description>
			Print version information to Max' console window.
	    </description>
	</method>
	<method name="report">
	    <description>
			Print version information to Max' console window.
	    </description>
	</method>
	
    </methodlist>

    <!--ATTRIBUTES-->
    <attributelist>
	<attribute name="mode" get="0" set="0" type="int" size="1" value="Mode">
		<description>
		<p>The display mode of the GUI-box.</p> 
		Modes are: 
		<ul>
			<li>1: 1 view  &#8212; xy-view, <m>top-down</m></li>
			<li>2: 1.5 views high  &#8212; xy-view <m>top-down</m>, and half a xz-view <m>back-to-front</m></li>
			<li>3: 2 views high &#8212;  xy-view <m>top-down</m>, and a xz-view <m>back-to-front</m>, arranged below</li>
			<li>4: 2 views wide  &#8212; xy-view <m>top-down</m>, and a xz-view <m>back-to-front</m>, arranged on the right</li>
		</ul>
		<p>Each view is constrained to a square (half-) surface, displaying either an xy-view (first view) or an xz-view (all other views). The xy-view can be considered as a <m>top-down</m> view, whereas the xz-views can be considered a view from <m>back-to-front</m>, when following the ICST-Ambisonic's <m>Coordinate System</m> convention.</p>
		</description>
	</attribute>
	
	<attribute name="point_size" get="0" set="0" type="float" size="1" value="Point Size">
	    <description>
			The size in pixels of the displayed points (default: 8.0).
	    </description>
	</attribute>
	
	<attribute name="numbers" get="0" set="0" type="onoff" size="1" value="Display Numbers/Names">
	    <description>
			 Activate/deactivate displaying the number or name of each point (default: off).
	    </description>
	</attribute>

	<attribute name="grid_display" get="0" set="0" type="int" size="1" value="Display Grid">
	    <description>
		<p> The grid display mode (default: 0 / off).</p>
		<p> Options are:</p>
		<ul>
			<li>0: Off</li>
			<li>1: aed  &#8212;  polar/spherical mode: circular grid</li>
			<li>0: xyz  &#8212; cartesian/rectangular mode: rectangular grid</li>
			<li>0: lat/lon  &#8212;  globe display: latitude-longitude grid</li>
		</ul>
	    </description>
	</attribute>
	
	<attribute name="grid_unit_xyz" get="0" set="0" type="float" size="1" value="Grid Unit xyz">
	    <description>
			The grid unit in rectangular mode, constrained between 0.01, 1.0 (default: 0.1 units).
	    </description>
	</attribute>
	
	<attribute name="grid_unit_ae" get="0" set="0" type="int" size="1" value="Grid Unit ae">
	    <description>
			The grid unit for azimuth, elevation in polar mode. Number of steps per 180 degrees, constrained to even values (default: 8 = 22.5 degrees per slice).
	    </description>
	</attribute>
	
	<attribute name="grid_unit_d" get="0" set="0" type="float" size="1" value="Grid Unit d">
	    <description>
			The grid unit for distance in polar mode, constrained between 0.01, 1.0 (default: 0.1 units).
	    </description>
	</attribute>
	
	<attribute name="grid_extend" get="0" set="0" type="onoff" size="1" value="Grid extension">
	    <description>
			Activate/deactivate displaying the grid beyond 1 unit (default: off).
	    </description>
	</attribute>
	
	<attribute name="coordinates" get="0" set="0" type="onoff" size="1" value="Display Coordinates">
	    <description>
			Activate/deactivate displaying the coordinates for each point (default: off).
	    </description>
	</attribute>	
	
	
	<attribute name="precision" get="0" set="0" type="int" size="1" value="Coord Display Precision">
	    <description>
			Set the number of decimal places for coordinate display (default: 6).
	    </description>
	</attribute>
	
	<attribute name="draw_labels" get="0" set="0" type="onoff" size="1" value="Display Labels">
	    <description>
			Activate/deactivate displaying the view and constraint labels (default: on).
	    </description>
	</attribute>
	
	<attribute name="draw_lines" get="0" set="0" type="onoff" size="1" value="Display Lines">
	    <description>
			Activate/deactivate displaying connecting lines between points in xy- and yz-views (in the vertical view modes only) (default: off).
	    </description>
	</attribute>	
	
	<attribute name="save_points" get="0" set="0" type="onoff" size="1" value="Save Points with Patcher">
	    <description>
			Activate/deactivate saving the current points with the patcher, to be reloaded next time (default: off).
	    </description>
	</attribute>	
	
	<attribute name="constrain" get="0" set="0" type="int" size="1" value="Constrain Method">
	    <description>
		<p>Set the constraining method for mouse and arrow point movement (default: off).</p>
		<p>Options are:</p>
			<ul>
			<li>0: off &#8212; no constraint</li>
			<li>1: grid-xyz &#8212; snap point to <bi>xyz</bi> grid (grid_unit_xyz)</li>
			<li>2: grid-aed &#8212; snap point to <bi>aed</bi> grid (grid_unit_ae &amp; grid_unit_d)</li>
			<li>3: grid-d &#8212; snap point to distance grid only (grid_unit_d)</li>
			<li>4: unit radius (2D &#8212; snap to radius 2D: force to circle with unit radius, discarding elevation.</li>
			<li>5: unit sphere (3D) &#8212; snap to sphere 3D: force to sphere with unit radius</li>
			<!-- <li>skirt radius 2D: inside radius forces to circle with 'constrain radius', outside remains unaffected</li>
			<li>skirt sphere 3D: inside radius forces to sphere with 'constrain radius', outside remains unaffected</li> -->
		</ul>
	    </description>
	</attribute>
	
	<attribute name="interpolation_mode" get="0" set="0" type="int" size="1" value="Snapshot Interpolation Mode">
	    <description>
			<p>Set the mode for interpolating between snapshots (default: linear).</p>
			<p>Options are:</p>
				<ul>
					<li>0: linear &#8212; interpolate in xyz coordinates</li>
					<li>1: polar &#8212; interpolate in aed coordinates</li>
				</ul>
			</description>
	</attribute>
	
	<attribute name="interpolation_time" get="0" set="0" type="int" size="1" value="Snapshot Interpolation Time">
	    <description>
			Snapshot interpolation time in ms (default: 0).
	    </description>
	</attribute>

	<attribute name="interval" get="0" set="0" type="int" size="1" value="Snapshot Interpolation Interval">
	    <description>
			Snapshot interpolation interval in ms (default: 20.0).
	    </description>
	</attribute>

	<attribute name="offset" get="0" set="0" type="int" size="1" value="Index Offset">
	    <description>
			Offset to add to point output (default: 0).
	    </description>
	</attribute>
	
	<attribute name="nudge_unit_xyz" get="0" set="0" type="float" size="1" value="Nudge Unit xyz">
	    <description>
			Unit for each arrow nudging movement in xyz (default: 0.01).
	    </description>
	</attribute>		
	
	<attribute name="nudge_unit_ae" get="0" set="0" type="float" size="1" value="Nudge Unit ae">
	    <description>
			Unit for each arrow nudging movement in azimuth/elevation (default: 1.0).
	    </description>
	</attribute>
	
	<attribute name="nudge_unit_d" get="0" set="0" type="float" size="1" value="Nudge Unit d">
	    <description>
			Unit for each arrow nudging movement in polar distance (default: 0.01).
	    </description>
	</attribute>	
	
	<attribute name="zoom_scale" get="0" set="0" type="float" size="1" value="Zoom Scale">
	    <description>
			View zoom scale (default: 1.0).
	    </description>
	</attribute>
	
	<attribute name="zoom_focal_point" get="0" set="0" type="float" size="3" value="Zoom Focal Point">
	    <description>
			View zoom focal point (default: 0.0 0.0 0.0).
	    </description>
	</attribute>		
	
	<attribute name="bg_image_mode" get="0" set="0" type="int" size="1" value="Backgroudn Image Mode">
	    <description>
			<p>Backgroudn Image Mode (default: off).</p>
			<p>Options are:</p>
				<ul>
					<li>0: Off &#8212; interpolate in xyz coordinates</li>
					<li>1: Repeated &#8212; repeat image for each view</li>
					<li>2: Full &#8212; draw image across all views</li>
				</ul>
			</description>
	</attribute>
	
	<attribute name="bg_image_file" get="0" set="0" type="file" size="1" value="Background Image File">
	    <description>
			Background Image File (default: "none").
	    </description>
	</attribute>
	
	<attribute name="pt_image_file" get="0" set="0" type="file" size="1" value="Point Image File">
	    <description>
			Point image file for points in group 1 (default: "none").
	    </description>
	</attribute>
	
	<attribute name="pt_image_file 1-7" get="0" set="0" type="file" size="1" value="Point Image File 1-7">
	    <description>
			Point image file for points in group 2&#8212;8 (default: "none").
	    </description>
	</attribute>	
		
	<attribute name="ignorekeys" get="0" set="0" type="onoff" size="1" value="Ignore Keyboard">
	    <description>
			Activate/deactivate keyboard interaction (default: on).
	    </description>
	</attribute>	
		
	<attribute name="number_font_name" get="0" set="0" type="symbol" size="1" value="Number / Name Font Name">
	    <description>
			Number / Name Font Name (default: Arial).
	    </description>
	</attribute>		
		
	<attribute name="number_font_size" get="0" set="0" type="float" size="1" value="Number / Name Font Size">
	    <description>
			Number / Name Font Size (default: 10).
	    </description>
	</attribute>		
		
	<attribute name="number_font_size" get="0" set="0" type="int" size="1" value="Number / Name Font Style">
	    <description>
			<p>Number / Name Font Style</p>
			<p> Options: 0 <m>regular</m>; 1 <m>bold</m>; 2 <m>italic</m>; 3 <m>bold italic</m> (default: 0 <m>regular</m>).</p>
	    </description>
	</attribute>		
		
	<attribute name="coord_font_name" get="0" set="0" type="symbol" size="1" value="Coordinate Font Name">
	    <description>
			Coordinate Font Name (default: Arial).
	    </description>
	</attribute>		
		
	<attribute name="coord_font_size" get="0" set="0" type="float" size="1" value="Coordinate Font Size">
	    <description>
			Coordinate Font Size (default: 9).
	    </description>
	</attribute>		
		
	<attribute name="coord_font_size" get="0" set="0" type="int" size="1" value="Coordinate Font Style">
	    <description>
			<p>Coordinate Font Style</p>
			<p> Options: 0 <m>regular</m>; 1 <m>bold</m>; 2 <m>italic</m>; 3 <m>bold italic</m> (default: 0 <m>regular</m>).</p>
	    </description>
	</attribute>
	
	<attribute name="label_font_name" get="0" set="0" type="symbol" size="1" value="Label Font Name">
	    <description>
			Label Font Name (default: Arial).
	    </description>
	</attribute>		
		
	<attribute name="label_font_size" get="0" set="0" type="float" size="1" value="Label Font Size">
	    <description>
			Label Font Size (default: 7).
	    </description>
	</attribute>		
		
	<attribute name="label_font_size" get="0" set="0" type="int" size="1" value="Label Font Style">
	    <description>
			<p>Label Font Style</p>
			<p> Options: 0 <m>regular</m>; 1 <m>bold</m>; 2 <m>italic</m>; 3 <m>bold italic</m> (default: 0 <m>regular</m>).</p>
	    </description>
	</attribute>			
	
	<attribute name="bgcolor" get="0" set="0" type="rgba" size="1" value="Background Color">
	    <description>
			<p>Background color (default: 0.018106 0.189806 0.327063 1.0)</p>
	    </description>
	</attribute>	
	
	<attribute name="bgcolor" get="0" set="0" type="rgba" size="1" value="Grid Color">
	    <description>
			<p>Grid color (default: 1.0 1.0 1.0 0.15)</p>
	    </description>
	</attribute>		
	
	<attribute name="hi_grid_color" get="0" set="0" type="rgba" size="1" value="Highlighted Grid Color">
	    <description>
			<p>Highlighted grid color (default: 1.0 1.0 1.0 0.2)</p>
	    </description>
	</attribute>		
	
	<attribute name="centre_color" get="0" set="0" type="rgba" size="1" value="Centre Zone Color">
	    <description>
			<p>Centre zone color (default: 1.0 1.0 1.0 0.05)</p>
	    </description>
	</attribute>	
	
	<attribute name="name_color" get="0" set="0" type="rgba" size="1" value="Name / Number Color">
	    <description>
			<p>Name / number color (default: 1.0 1.0 1.0 0.5)</p>
	    </description>
	</attribute>	
	
	<attribute name="group_name_color" get="0" set="0" type="onoff" size="1" value="Name Color = Group Color">
	    <description>
			Activate/deactivate Name Color = Group Color (default: off).
	    </description>
	</attribute>	
	
	<attribute name="label_color" get="0" set="0" type="rgba" size="1" value="Label Color">
	    <description>
			<p>Label color (default: 1.0 1.0 1.0 0.25)</p>
	    </description>
	</attribute>
	
	<attribute name="border_color" get="0" set="0" type="rgba" size="1" value="Border Color">
	    <description>
			<p>Border color (default: 0.517647 0.51764 0.51764 0.0)</p>
	    </description>
	</attribute>
	
	<attribute name="hi_border_color" get="0" set="0" type="rgba" size="1" value="Highlighted Border Color">
	    <description>
			<p>Highlighted Border color (default: 1.0 0.57769 0.46156 0.501961)</p>
	    </description>
	</attribute>	
	
	<attribute name="coord_color" get="0" set="0" type="rgba" size="1" value="Coordinates Color">
	    <description>
			<p>Coordinates color (default: 1.0 1.0 1.0 0.26)</p>
	    </description>
	</attribute>	
	
	<attribute name="point_color" get="0" set="0" type="rgba" size="1" value="Point Color">
	    <description>
			<p>Point color for group 1 (default: 1.0 0.729411764705882 0.2 1.0)</p>
	    </description>
	</attribute>
	
	<attribute name="point_color2-8" get="0" set="0" type="rgba" size="1" value="Point Color 2-8">
	    <description>
			<p>Point color for group 2&#8212;8 (default: varying, rainbow)</p>
	    </description>
	</attribute>
	
	<attribute name="line_color" get="0" set="0" type="rgba" size="1" value="Line Color">
	    <description>
			<p>Line color (default: 1.0 1.0 1.0 0.5)</p>
	    </description>
	</attribute>		
    </attributelist>
	
	<!-- Inlets/Uutlets-->
    <misc name = "Input">
	<entry name ="Inlet 1 [bang, int, float, list, anything]">
	    <description>
		Coordinates, messages.
	    </description>
	</entry>
    </misc>

    <misc name = "Output">
	<entry name ="Outlet 1 [list]">
	    <description>
			<p>Polar/spherical coordinates in ambipoint format:</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>Cartesian/rectangular coordinates in ambipoint format:</p> 
			<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>
	</entry>
	<entry name ="Outlet 3 [list]">
	    <description>
			Outputs notifications for mouse, zoom, state, edit_point, etc....
	    </description>
	</entry>
    </misc>

    <misc name = "Discussion">
	<entry name ="Keywords">
	    <description>
		ambimonitor, GUI, spatialisation, control, mouse, keyboard, snapshots
	    </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>
