[postgis-tickets] r16705 - Move ST_QuantizeCoordinates from miscellaneous to Editors and fix the first example

Regina Obe lr at pcorp.us
Tue Aug 28 12:25:28 PDT 2018


Author: robe
Date: 2018-08-28 00:25:28 -0700 (Tue, 28 Aug 2018)
New Revision: 16705

Modified:
   branches/2.5/doc/reference_editor.xml
   branches/2.5/doc/reference_misc.xml
Log:
Move ST_QuantizeCoordinates from miscellaneous to Editors and fix the first example

Modified: branches/2.5/doc/reference_editor.xml
===================================================================
--- branches/2.5/doc/reference_editor.xml	2018-08-28 07:08:59 UTC (rev 16704)
+++ branches/2.5/doc/reference_editor.xml	2018-08-28 07:25:28 UTC (rev 16705)
@@ -1074,6 +1074,180 @@
 		</refsection>
 	</refentry>
 
+	<refentry id="ST_QuantizeCoordinates">
+		<refnamediv>
+			<refname>
+				ST_QuantizeCoordinates
+			</refname>
+			<refpurpose>
+				Sets least significant bits of coordinates to zero
+			</refpurpose>
+		</refnamediv>
+
+		<refsynopsisdiv>
+			<funcsynopsis>
+				<funcprototype>
+					<funcdef>
+						geometry
+						<function>ST_QuantizeCoordinates</function>
+					</funcdef>
+					<paramdef>
+						<type>geometry</type>
+						<parameter>g</parameter>
+					</paramdef>
+					<paramdef>
+						<type>int</type>
+						<parameter>prec_x</parameter>
+					</paramdef>
+					<paramdef>
+						<type>int</type>
+						<parameter>prec_y</parameter>
+					</paramdef>
+					<paramdef>
+						<type>int</type>
+						<parameter>prec_z</parameter>
+					</paramdef>
+					<paramdef>
+						<type>int</type>
+						<parameter>prec_m</parameter>
+					</paramdef>
+				</funcprototype>
+			</funcsynopsis>
+		</refsynopsisdiv>
+
+		<refsection>
+			<title>Description</title>
+			<para>
+				<code>ST_QuantizeCoordinates</code> determines the number of bits
+				(<code>N</code>) required to represent a coordinate value with a
+				specified number of digits after the decimal point, and then sets
+				all but the <code>N</code> most significant bits to zero. The
+				resulting coordinate value will still round to the original value,
+				but will have improved compressiblity. This can result in a
+				significant disk usage reduction provided that the geometry column
+				is using a <ulink
+				url="https://www.postgresql.org/docs/current/static/storage-toast.html#STORAGE-TOAST-ONDISK">
+				compressible storage type</ulink>. The function allows
+				specification of a different number of digits after the decimal
+				point in each dimension; unspecified dimensions are assumed to have
+				the precsion of the <code>x</code> dimension. Negative digits are
+				interpreted to refer digits to the left of the decimal point, (i.e.,
+				<code>prec_x=-2</code> will preserve coordinate values to the
+				nearest 100.
+			</para>
+			<para>
+				The coordinates produced by <code>ST_QuantizeCoordinates</code> are
+				independent of the geometry that contains those coordinates and the
+				relative position of those coordinates within the geometry. As a result,
+				existing topological relationships between geometries are unaffected
+				by use of this function. The function may produce invalid geometry
+				when it is called with a number of digits lower than the intrinsic
+				precision of the geometry.
+			</para>
+			<para>Availability: 2.5.0</para>
+		</refsection>
+		<refsection>
+			<title>Technical Background</title>
+			<para>
+				PostGIS stores all coordinate values as double-precision floating
+				point integers, which can reliably represent 15 significant digits.
+				However, PostGIS may be used to manage data that intrinsically has
+				fewer than 15 significant digits. An example is TIGER data, which is
+				provided as geographic coordinates with six digits of precision
+				after the decimal point (thus requiring only nine significant digits
+				of longitude and eight significant digits of latitude.)
+			</para>
+			<para>
+				When 15 significant digits are available, there are many possible
+				representations of a number with 9 significant digits.  A double
+				precision floating point number uses 52 explicit bits to represent
+				the significand (mantissa) of the coordinate. Only 30 bits are needed
+				to represent a mantissa with 9 significant digits, leaving 22
+				insignificant bits; we can set their value to anything we like and
+				still end up with a number that rounds to our input value.  For
+				example, the value 100.123456 can be represented by the floating
+				point numbers closest to 100.123456000000, 100.123456000001, and
+				100.123456432199. All are equally valid, in that
+				<code>ST_AsText(geom, 6)</code> will return the same result with
+				any of these inputs. As we can set these bits to any value,
+				<code>ST_QuantizeCoordinates</code> sets the 22 insignificant
+				bits to zero. For a long coordinate sequence this creates a
+				pattern of blocks of consecutive zeros that is compressed
+				by PostgreSQL more effeciently.
+			</para>
+
+			<note>
+				<para>
+					Only the on-disk size of the geometry is potentially affected by
+					<code>ST_QuantizeCoordinates</code>.  <xref linkend="ST_MemSize"></xref>,
+					which reports the in-memory usage of the geometry, will return the
+					the same value regardless of the disk space used by a geometry.
+				</para>
+			</note>
+		</refsection>
+
+		<refsection>
+			<title>Examples</title>
+
+			<programlisting>SELECT ST_AsText(ST_QuantizeCoordinates('POINT (100.123456 0)'::geometry, 4));
+st_astext
+-------------------------
+POINT(100.123455047607 0)
+			</programlisting>
+
+			<programlisting>WITH test AS (SELECT 'POINT (123.456789123456 123.456789123456)'::geometry AS geom)
+SELECT
+  digits,
+  encode(ST_QuantizeCoordinates(geom, digits), 'hex'),
+  ST_AsText(ST_QuantizeCoordinates(geom, digits))
+FROM test, generate_series(15, -15, -1) AS digits;
+
+digits  |                   encode                   |                st_astext
+--------+--------------------------------------------+------------------------------------------
+15      | 01010000005f9a72083cdd5e405f9a72083cdd5e40 | POINT(123.456789123456 123.456789123456)
+14      | 01010000005f9a72083cdd5e405f9a72083cdd5e40 | POINT(123.456789123456 123.456789123456)
+13      | 01010000005f9a72083cdd5e405f9a72083cdd5e40 | POINT(123.456789123456 123.456789123456)
+12      | 01010000005c9a72083cdd5e405c9a72083cdd5e40 | POINT(123.456789123456 123.456789123456)
+11      | 0101000000409a72083cdd5e40409a72083cdd5e40 | POINT(123.456789123456 123.456789123456)
+10      | 0101000000009a72083cdd5e40009a72083cdd5e40 | POINT(123.456789123455 123.456789123455)
+9       | 0101000000009072083cdd5e40009072083cdd5e40 | POINT(123.456789123418 123.456789123418)
+8       | 0101000000008072083cdd5e40008072083cdd5e40 | POINT(123.45678912336 123.45678912336)
+7       | 0101000000000070083cdd5e40000070083cdd5e40 | POINT(123.456789121032 123.456789121032)
+6       | 0101000000000040083cdd5e40000040083cdd5e40 | POINT(123.456789076328 123.456789076328)
+5       | 0101000000000000083cdd5e40000000083cdd5e40 | POINT(123.456789016724 123.456789016724)
+4       | 0101000000000000003cdd5e40000000003cdd5e40 | POINT(123.456787109375 123.456787109375)
+3       | 0101000000000000003cdd5e40000000003cdd5e40 | POINT(123.456787109375 123.456787109375)
+2       | 01010000000000000038dd5e400000000038dd5e40 | POINT(123.45654296875 123.45654296875)
+1       | 01010000000000000000dd5e400000000000dd5e40 | POINT(123.453125 123.453125)
+0       | 01010000000000000000dc5e400000000000dc5e40 | POINT(123.4375 123.4375)
+-1      | 01010000000000000000c05e400000000000c05e40 | POINT(123 123)
+-2      | 01010000000000000000005e400000000000005e40 | POINT(120 120)
+-3      | 010100000000000000000058400000000000005840 | POINT(96 96)
+-4      | 010100000000000000000058400000000000005840 | POINT(96 96)
+-5      | 010100000000000000000058400000000000005840 | POINT(96 96)
+-6      | 010100000000000000000058400000000000005840 | POINT(96 96)
+-7      | 010100000000000000000058400000000000005840 | POINT(96 96)
+-8      | 010100000000000000000058400000000000005840 | POINT(96 96)
+-9      | 010100000000000000000058400000000000005840 | POINT(96 96)
+-10     | 010100000000000000000058400000000000005840 | POINT(96 96)
+-11     | 010100000000000000000058400000000000005840 | POINT(96 96)
+-12     | 010100000000000000000058400000000000005840 | POINT(96 96)
+-13     | 010100000000000000000058400000000000005840 | POINT(96 96)
+-14     | 010100000000000000000058400000000000005840 | POINT(96 96)
+-15     | 010100000000000000000058400000000000005840 | POINT(96 96)
+</programlisting>
+
+		</refsection>
+
+		<refsection>
+			<title>See Also</title>
+
+			<para><xref linkend="ST_SnapToGrid" /></para>
+		</refsection>
+
+	</refentry>
+
+
 	<refentry id="ST_RemovePoint">
 	  <refnamediv>
 		<refname>ST_RemovePoint</refname>
@@ -1556,6 +1730,7 @@
 			given <varname>max_segment_length</varname>.  Distance computation is performed in 2d
 			only. For geometry, length units are in units of spatial reference.  For geography, units are in meters.</para>
 			<para>Availability: 1.2.2</para>
+			<para>Enhanced: 3.0.0 Segmentize geometry now uses equal length segments</para>
 			<para>Enhanced: 2.3.0 Segmentize geography now uses equal length segments</para>
 			<para>Enhanced: 2.1.0 support for geography was introduced.</para>
 			<para>Changed: 2.1.0 As a result of the introduction of geography support: The construct <code>SELECT ST_Segmentize('LINESTRING(1 2, 3 4)',0.5);</code> will result in ambiguous function error.  You need to have properly typed object e.g. a geometry/geography column, use ST_GeomFromText, ST_GeogFromText or

Modified: branches/2.5/doc/reference_misc.xml
===================================================================
--- branches/2.5/doc/reference_misc.xml	2018-08-28 07:08:59 UTC (rev 16704)
+++ branches/2.5/doc/reference_misc.xml	2018-08-28 07:25:28 UTC (rev 16705)
@@ -695,178 +695,5 @@
 	  </refsection>
 	</refentry>
 
-	<refentry id="ST_QuantizeCoordinates">
-		<refnamediv>
-			<refname>
-				ST_QuantizeCoordinates
-			</refname>
-			<refpurpose>
-				Sets least significant bits of coordinates to zero
-			</refpurpose>
-		</refnamediv>
 
-		<refsynopsisdiv>
-			<funcsynopsis>
-				<funcprototype>
-					<funcdef>
-						geometry
-						<function>ST_QuantizeCoordinates</function>
-					</funcdef>
-					<paramdef>
-						<type>geometry</type>
-						<parameter>g</parameter>
-					</paramdef>
-					<paramdef>
-						<type>int</type>
-						<parameter>prec_x</parameter>
-					</paramdef>
-					<paramdef>
-						<type>int</type>
-						<parameter>prec_y</parameter>
-					</paramdef>
-					<paramdef>
-						<type>int</type>
-						<parameter>prec_z</parameter>
-					</paramdef>
-					<paramdef>
-						<type>int</type>
-						<parameter>prec_m</parameter>
-					</paramdef>
-				</funcprototype>
-			</funcsynopsis>
-		</refsynopsisdiv>
-
-		<refsection>
-			<title>Description</title>
-			<para>
-				<code>ST_QuantizeCoordinates</code> determines the number of bits
-				(<code>N</code>) required to represent a coordinate value with a
-				specified number of digits after the decimal point, and then sets
-				all but the <code>N</code> most significant bits to zero. The
-				resulting coordinate value will still round to the original value,
-				but will have improved compressiblity. This can result in a
-				significant disk usage reduction provided that the geometry column
-				is using a <ulink
-				url="https://www.postgresql.org/docs/current/static/storage-toast.html#STORAGE-TOAST-ONDISK">
-				compressible storage type</ulink>. The function allows
-				specification of a different number of digits after the decimal
-				point in each dimension; unspecified dimensions are assumed to have
-				the precsion of the <code>x</code> dimension. Negative digits are
-				interpreted to refer digits to the left of the decimal point, (i.e.,
-				<code>prec_x=-2</code> will preserve coordinate values to the
-				nearest 100. 
-			</para>
-			<para>
-				The coordinates produced by <code>ST_QuantizeCoordinates</code> are
-				independent of the geometry that contains those coordinates and the
-				relative position of those coordinates within the geometry. As a result,
-				existing topological relationships between geometries are unaffected
-				by use of this function. The function may produce invalid geometry
-				when it is called with a number of digits lower than the intrinsic
-				precision of the geometry.
-			</para>
-			<para>Availability: 2.5.0</para>
-		</refsection>
-		<refsection>
-			<title>Technical Background</title>
-			<para>
-				PostGIS stores all coordinate values as double-precision floating
-				point integers, which can reliably represent 15 significant digits.
-				However, PostGIS may be used to manage data that intrinsically has
-				fewer than 15 significant digits. An example is TIGER data, which is
-				provided as geographic coordinates with six digits of precision
-				after the decimal point (thus requiring only nine significant digits
-				of longitude and eight significant digits of latitude.)
-			</para>
-			<para>
-				When 15 significant digits are available, there are many possible
-				representations of a number with 9 significant digits.  A double
-				precision floating point number uses 52 explicit bits to represent
-				the significand (mantissa) of the coordinate. Only 30 bits are needed
-				to represent a mantissa with 9 significant digits, leaving 22
-				insignificant bits; we can set their value to anything we like and
-				still end up with a number that rounds to our input value.  For
-				example, the value 100.123456 can be represented by the floating
-				point numbers closest to 100.123456000000, 100.123456000001, and
-				100.123456432199. All are equally valid, in that
-				<code>ST_AsText(geom, 6)</code> will return the same result with 
-				any of these inputs. As we can set these bits to any value,
-				<code>ST_QuantizeCoordinates</code> sets the 22 insignificant
-				bits to zero. For a long coordinate sequence this creates a 
-				pattern of blocks of consecutive zeros that is compressed 
-				by PostgreSQL more effeciently.
-			</para>
-
-			<note>
-				<para>
-					Only the on-disk size of the geometry is potentially affected by
-					<code>ST_QuantizeCoordinates</code>.  <xref linkend="ST_MemSize"></xref>,
-					which reports the in-memory usage of the geometry, will return the
-					the same value regardless of the disk space used by a geometry.
-				</para>
-			</note>
-		</refsection>
-
-		<refsection>
-			<title>Examples</title>
-
-			<programlisting>SELECT ST_AsText(ST_QuantizeCoordinates('POINT (100.123456 0)'));
-st_astext
--------------------------
-POINT(100.123455941677 0)
-			</programlisting>
-
-			<programlisting>
-WITH test AS (SELECT 'POINT (123.456789123456 123.456789123456)'::geometry AS geom)
-SELECT
-  digits,
-  encode(ST_QuantizeCoordinates(geom, digits), 'hex'),
-  ST_AsText(ST_QuantizeCoordinates(geom, digits))
-FROM test, generate_series(15, -15, -1) AS digits;
-
-digits  |                   encode                   |                st_astext                 
---------+--------------------------------------------+------------------------------------------
-15      | 01010000005f9a72083cdd5e405f9a72083cdd5e40 | POINT(123.456789123456 123.456789123456)
-14      | 01010000005f9a72083cdd5e405f9a72083cdd5e40 | POINT(123.456789123456 123.456789123456)
-13      | 01010000005f9a72083cdd5e405f9a72083cdd5e40 | POINT(123.456789123456 123.456789123456)
-12      | 01010000005c9a72083cdd5e405c9a72083cdd5e40 | POINT(123.456789123456 123.456789123456)
-11      | 0101000000409a72083cdd5e40409a72083cdd5e40 | POINT(123.456789123456 123.456789123456)
-10      | 0101000000009a72083cdd5e40009a72083cdd5e40 | POINT(123.456789123455 123.456789123455)
-9       | 0101000000009072083cdd5e40009072083cdd5e40 | POINT(123.456789123418 123.456789123418)
-8       | 0101000000008072083cdd5e40008072083cdd5e40 | POINT(123.45678912336 123.45678912336)
-7       | 0101000000000070083cdd5e40000070083cdd5e40 | POINT(123.456789121032 123.456789121032)
-6       | 0101000000000040083cdd5e40000040083cdd5e40 | POINT(123.456789076328 123.456789076328)
-5       | 0101000000000000083cdd5e40000000083cdd5e40 | POINT(123.456789016724 123.456789016724)
-4       | 0101000000000000003cdd5e40000000003cdd5e40 | POINT(123.456787109375 123.456787109375)
-3       | 0101000000000000003cdd5e40000000003cdd5e40 | POINT(123.456787109375 123.456787109375)
-2       | 01010000000000000038dd5e400000000038dd5e40 | POINT(123.45654296875 123.45654296875)
-1       | 01010000000000000000dd5e400000000000dd5e40 | POINT(123.453125 123.453125)
-0       | 01010000000000000000dc5e400000000000dc5e40 | POINT(123.4375 123.4375)
--1      | 01010000000000000000c05e400000000000c05e40 | POINT(123 123)
--2      | 01010000000000000000005e400000000000005e40 | POINT(120 120)
--3      | 010100000000000000000058400000000000005840 | POINT(96 96)
--4      | 010100000000000000000058400000000000005840 | POINT(96 96)
--5      | 010100000000000000000058400000000000005840 | POINT(96 96)
--6      | 010100000000000000000058400000000000005840 | POINT(96 96)
--7      | 010100000000000000000058400000000000005840 | POINT(96 96)
--8      | 010100000000000000000058400000000000005840 | POINT(96 96)
--9      | 010100000000000000000058400000000000005840 | POINT(96 96)
--10     | 010100000000000000000058400000000000005840 | POINT(96 96)
--11     | 010100000000000000000058400000000000005840 | POINT(96 96)
--12     | 010100000000000000000058400000000000005840 | POINT(96 96)
--13     | 010100000000000000000058400000000000005840 | POINT(96 96)
--14     | 010100000000000000000058400000000000005840 | POINT(96 96)
--15     | 010100000000000000000058400000000000005840 | POINT(96 96)
-</programlisting>
-
-		</refsection>
-
-		<refsection>
-			<title>See Also</title>
-
-			<para><xref linkend="ST_SnapToGrid" /></para>
-		</refsection>
-
-	</refentry>
-
  </sect1>



More information about the postgis-tickets mailing list