Help - Commit missing files

Help/Developer Information/Astronomical Coordinates.aml

@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="utf-8"?>
+<topic id="72A95B28-BBE2-4C7D-BC03-2D6AB324B6F7" revisionNumber="1">
+  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
+	<section address="Astronomical Coordinates">
+		<title>Astronomical Coordinates</title>
+   		<content>
+		    <para>The official classical sequence of [RA,Dec] coordinate systems is as follows (neglecting proper motion and various sub-arcsecond effects):</para>
+			<para>
+				<mediaLink>
+					<image placement="center" xlink:href="Astronomical Coordinates"/>
+				</mediaLink>
+			</para>
+      	</content>
+    </section>
+       <section address="Disambiguation">
+    	<title>Disambiguation</title>
+  		<content>
+ 			<list class="ordered">
+			  <listItem>
+					<para>The term "JNow", unknown in professional circles, is confusing, because the "J" implies that JNow is the "today" equivalent of "J2000",
+			    	which was 2000 Jan 1.5. It isn't - even at exactly 2000 Jan 1.5, stars weren't at their J2000.0 positions, but up to 30 arcseconds away, because 
+			    	of aberration and nutation.</para>
+			    	<para>For this reason, <legacyBold>use of the term "JNow" is not recommended</legacyBold>. If you do come across it, it will most likely refer to observed coordinates.</para>
+			  </listItem>
+			  <listItem>
+					<para>When discussing coordinates, the term "Local Topocentric" is sometimes seen. The intention of the phrase is to refer to an object's coordinates at the current date/time, 
+					however, the term "Topocentric" already carries this meaning and prefixing it with "Local" adds no further information.</para>
+					<para>For this reason, <legacyBold>use of the term "Local Topocentric" is not recommended</legacyBold>, "Topocentric" does the job more concisely.</para>
+					<para>Historically, the ASCOM EquatorialCoordinate Type enumeration contained the member "equLocalTopocentric" and this name has now been deprecated 
+					in favour of the new member equTopocentric. This is a non-breaking change and continued use of equLocalTopocentric will just show up as a warning when compiling ASCOM drivers and applications.</para>
+			  </listItem>
+ 	       </list>
+      </content>
+	</section>
+
+    <section address="Notes">
+    	<title>Notes</title>
+  		<content>
+ 			<list class="ordered">
+			  <listItem>		    		
+	    		<para>
+		    		When designing your driver you need to choose which type of coordinates you will accept and the <codeEntityReference>T:ASCOM.DeviceInterface.ITelescopeV3</codeEntityReference>
+		    		interface provides the <codeEntityReference>P:ASCOM.DeviceInterface.ITelescopeV3.DoesRefraction</codeEntityReference> and 
+		    		<codeEntityReference>P:ASCOM.DeviceInterface.ITelescopeV3.EquatorialSystem</codeEntityReference> properties for this purpose. The full range of coorindate systems recognised are described here: 
+		    		<codeEntityReference>T:ASCOM.DeviceInterface.EquatorialCoordinateType</codeEntityReference>.
+		    		Usually you would accept one or more of <legacyBold>J2000</legacyBold>, <legacyBold>Topocentric</legacyBold> or <legacyBold>Observed</legacyBold> coordinates at your discretion.
+		    		To specify a particular coordinate type you must set the properties as below:
+		    		<list class="bullet">
+			    		<listItem>
+				    		<para>
+					    		<legacyBold>J2000.0</legacyBold> - Set <codeEntityReference>P:ASCOM.DeviceInterface.ITelescopeV3.EquatorialSystem</codeEntityReference> to 
+					    		<codeEntityReference>F:ASCOM.DeviceInterface.EquatorialCoordinateType.equJ2000</codeEntityReference> and 
+					    		<codeEntityReference>P:ASCOM.DeviceInterface.ITelescopeV3.DoesRefraction</codeEntityReference> to <codeInline>True</codeInline>.
+					    		Your driver / mount will correct the supplied coordinates for aberration, precession, nutation and refraction.
+				    		</para>
+				    		</listItem>
+			    		<listItem>
+				    		<para>
+					    		<legacyBold>TOPOCENTRIC</legacyBold> - Set <codeEntityReference>P:ASCOM.DeviceInterface.ITelescopeV3.EquatorialSystem</codeEntityReference> to
+					    		<codeEntityReference>F:ASCOM.DeviceInterface.EquatorialCoordinateType.equTopocentric</codeEntityReference> and
+					    		<codeEntityReference>P:ASCOM.DeviceInterface.ITelescopeV3.DoesRefraction</codeEntityReference> to <codeInline>True</codeInline>.
+					    		Your driver / mount will correct the supplied coordinates for refraction.
+				    		</para>
+				    	</listItem>
+			    		<listItem>
+				    		<para>
+					    		<legacyBold>OBSERVED</legacyBold> -Set <codeEntityReference>P:ASCOM.DeviceInterface.ITelescopeV3.EquatorialSystem</codeEntityReference> to 
+					    		<codeEntityReference>F:ASCOM.DeviceInterface.EquatorialCoordinateType.equTopocentric</codeEntityReference> and
+					    		<codeEntityReference>P:ASCOM.DeviceInterface.ITelescopeV3.DoesRefraction</codeEntityReference> to <codeInline>False</codeInline>.
+					    		Your driver / mount will use the coordinates as supplied.
+				    		</para>
+			    		</listItem>
+		    		</list>
+	    		</para>
+	    		<para>If you wish the user to be able to select the coordinate type that your driver will receive, you can implement Set methods for the 
+	    		<codeEntityReference>P:ASCOM.DeviceInterface.ITelescopeV3.EquatorialSystem</codeEntityReference> and <codeEntityReference>P:ASCOM.DeviceInterface.ITelescopeV3.DoesRefraction</codeEntityReference> properties.
+	    		Your driver / mount should then process the coordinates as described above.</para>
+			  </listItem>
+			  <listItem><para>"Apparent place" differs from topocentric because of diurnal aberration, a sub-arcsecond effect.</para></listItem>
+			  <listItem><para>Modern "ICRS" coordinates are the same as J2000.0 mean place to better than 0.025 arcsec.</para></listItem>
+			</list>
+        </content>
+	</section>
+  </developerConceptualDocument>
+</topic>