[api] Add methods to create triangular, square, and sine-like waves

along a geometry's boundaries also includes variations on these which allow for randomized triangle/square/sine-like waves, with amplitude and wavelength randomly generated using a specified range
qgis · Oct 22, 2021 · 430c5b2 · 430c5b2
1 parent e87c2d6
commit 430c5b2
Show file tree

Hide file tree

Showing 6 changed files with 1,436 additions and 0 deletions.
diff --git a/python/core/auto_generated/geometry/qgsgeometry.sip.in b/python/core/auto_generated/geometry/qgsgeometry.sip.in
@@ -1026,6 +1026,114 @@ iterations is reached. The angle threshold parameter specifies how close to a ri
 straight line an angle must be before it is attempted to be straightened.
 
 .. versionadded:: 3.0
+%End
+
+    QgsGeometry triangularWaves( double wavelength, double amplitude, bool strictWavelength = false ) const;
+%Docstring
+Constructs triangular waves along the boundary of the geometry, with the
+specified ``wavelength`` and ``amplitude``.
+
+By default the ``wavelength`` argument is treated as a "maximum wavelength", where the actual
+wavelength will be dynamically adjusted so that an exact number of triangular waves are created
+along the boundaries of the geometry. If ``strictWavelength`` is set to ``True`` then the ``wavelength``
+will be used exactly and an incomplete pattern may be used for the final waveform.
+
+.. seealso:: :py:func:`triangularWavesRandomized`
+
+.. versionadded:: 3.24
+%End
+
+    QgsGeometry triangularWavesRandomized( double minimumWavelength, double maximumWavelength, double minimumAmplitude, double maximumAmplitude, unsigned long seed = 0 ) const;
+%Docstring
+Constructs randomized triangular waves along the boundary of the geometry, with the
+specified wavelength and amplitude ranges.
+
+The ``minimumWavelength`` and ``maximumWavelength`` arguments set the range for the randomized
+wavelength. This is evaluated for each individual triangular waveform created along the geometry
+boundaries, so the resultant geometry will consist of many different wavelengths.
+
+Similarly, the ``minimumAmplitude`` and ``maximumAmplitude`` arguments define the range for the
+randomized amplitude of the triangular components. Randomized amplitude values will be calculated
+individually for triangles placed on each either side of the input geometry boundaries.
+
+Optionally, a specific random ``seed`` can be used when generating points. If ``seed``
+is 0, then a completely random sequence of points will be generated.
+
+.. seealso:: :py:func:`triangularWaves`
+
+.. versionadded:: 3.24
+%End
+
+    QgsGeometry squareWaves( double wavelength, double amplitude, bool strictWavelength = false ) const;
+%Docstring
+Constructs square waves along the boundary of the geometry, with the
+specified ``wavelength`` and ``amplitude``.
+
+By default the ``wavelength`` argument is treated as a "maximum wavelength", where the actual
+wavelength will be dynamically adjusted so that an exact number of square waves are created
+along the boundaries of the geometry. If ``strictWavelength`` is set to ``True`` then the ``wavelength``
+will be used exactly and an incomplete pattern may be used for the final waveform.
+
+.. seealso:: :py:func:`squareWavesRandomized`
+
+.. versionadded:: 3.24
+%End
+
+    QgsGeometry squareWavesRandomized( double minimumWavelength, double maximumWavelength, double minimumAmplitude, double maximumAmplitude, unsigned long seed = 0 ) const;
+%Docstring
+Constructs randomized square waves along the boundary of the geometry, with the
+specified wavelength and amplitude ranges.
+
+The ``minimumWavelength`` and ``maximumWavelength`` arguments set the range for the randomized
+wavelength. This is evaluated for each individual square waveform created along the geometry
+boundaries, so the resultant geometry will consist of many different wavelengths.
+
+Similarly, the ``minimumAmplitude`` and ``maximumAmplitude`` arguments define the range for the
+randomized amplitude of the square components. Randomized amplitude values will be calculated
+individually for squares placed on each either side of the input geometry boundaries.
+
+Optionally, a specific random ``seed`` can be used when generating points. If ``seed``
+is 0, then a completely random sequence of points will be generated.
+
+.. seealso:: :py:func:`squareWaves`
+
+.. versionadded:: 3.24
+%End
+
+    QgsGeometry roundWaves( double wavelength, double amplitude, bool strictWavelength = false ) const;
+%Docstring
+Constructs rounded (sine-like) waves along the boundary of the geometry, with the
+specified ``wavelength`` and ``amplitude``.
+
+By default the ``wavelength`` argument is treated as a "maximum wavelength", where the actual
+wavelength will be dynamically adjusted so that an exact number of waves are created
+along the boundaries of the geometry. If ``strictWavelength`` is set to ``True`` then the ``wavelength``
+will be used exactly and an incomplete pattern may be used for the final waveform.
+
+.. seealso:: :py:func:`roundWavesRandomized`
+
+.. versionadded:: 3.24
+%End
+
+    QgsGeometry roundWavesRandomized( double minimumWavelength, double maximumWavelength, double minimumAmplitude, double maximumAmplitude, unsigned long seed = 0 ) const;
+%Docstring
+Constructs randomized rounded (sine-like) waves along the boundary of the geometry, with the
+specified wavelength and amplitude ranges.
+
+The ``minimumWavelength`` and ``maximumWavelength`` arguments set the range for the randomized
+wavelength. This is evaluated for each individual waveform created along the geometry
+boundaries, so the resultant geometry will consist of many different wavelengths.
+
+Similarly, the ``minimumAmplitude`` and ``maximumAmplitude`` arguments define the range for the
+randomized amplitude of the square components. Randomized amplitude values will be calculated
+individually for waves placed on each either side of the input geometry boundaries.
+
+Optionally, a specific random ``seed`` can be used when generating points. If ``seed``
+is 0, then a completely random sequence of points will be generated.
+
+.. seealso:: :py:func:`squareWaves`
+
+.. versionadded:: 3.24
 %End
 
     QgsGeometry snappedToGrid( double hSpacing, double vSpacing, double dSpacing = 0, double mSpacing = 0 ) const;

diff --git a/src/core/geometry/qgsgeometry.cpp b/src/core/geometry/qgsgeometry.cpp
@@ -1197,6 +1197,42 @@ QgsGeometry QgsGeometry::orthogonalize( double tolerance, int maxIterations, dou
   return engine.orthogonalize( tolerance, maxIterations, angleThreshold );
 }
 
+QgsGeometry QgsGeometry::triangularWaves( double wavelength, double amplitude, bool strictWavelength ) const
+{
+  QgsInternalGeometryEngine engine( *this );
+  return engine.triangularWaves( wavelength, amplitude, strictWavelength );
+}
+
+QgsGeometry QgsGeometry::triangularWavesRandomized( double minimumWavelength, double maximumWavelength, double minimumAmplitude, double maximumAmplitude, unsigned long seed ) const
+{
+  QgsInternalGeometryEngine engine( *this );
+  return engine.triangularWavesRandomized( minimumWavelength, maximumWavelength, minimumAmplitude, maximumAmplitude, seed );
+}
+
+QgsGeometry QgsGeometry::squareWaves( double wavelength, double amplitude, bool strictWavelength ) const
+{
+  QgsInternalGeometryEngine engine( *this );
+  return engine.squareWaves( wavelength, amplitude, strictWavelength );
+}
+
+QgsGeometry QgsGeometry::squareWavesRandomized( double minimumWavelength, double maximumWavelength, double minimumAmplitude, double maximumAmplitude, unsigned long seed ) const
+{
+  QgsInternalGeometryEngine engine( *this );
+  return engine.squareWavesRandomized( minimumWavelength, maximumWavelength, minimumAmplitude, maximumAmplitude, seed );
+}
+
+QgsGeometry QgsGeometry::roundWaves( double wavelength, double amplitude, bool strictWavelength ) const
+{
+  QgsInternalGeometryEngine engine( *this );
+  return engine.roundWaves( wavelength, amplitude, strictWavelength );
+}
+
+QgsGeometry QgsGeometry::roundWavesRandomized( double minimumWavelength, double maximumWavelength, double minimumAmplitude, double maximumAmplitude, unsigned long seed ) const
+{
+  QgsInternalGeometryEngine engine( *this );
+  return engine.roundWavesRandomized( minimumWavelength, maximumWavelength, minimumAmplitude, maximumAmplitude, seed );
+}
+
 QgsGeometry QgsGeometry::snappedToGrid( double hSpacing, double vSpacing, double dSpacing, double mSpacing ) const
 {
   if ( !d->geometry )

diff --git a/src/core/geometry/qgsgeometry.h b/src/core/geometry/qgsgeometry.h
@@ -1067,6 +1067,108 @@ class CORE_EXPORT QgsGeometry
      */
     QgsGeometry orthogonalize( double tolerance = 1.0E-8, int maxIterations = 1000, double angleThreshold = 15.0 ) const;
 
+    /**
+     * Constructs triangular waves along the boundary of the geometry, with the
+     * specified \a wavelength and \a amplitude.
+     *
+     * By default the \a wavelength argument is treated as a "maximum wavelength", where the actual
+     * wavelength will be dynamically adjusted so that an exact number of triangular waves are created
+     * along the boundaries of the geometry. If \a strictWavelength is set to TRUE then the \a wavelength
+     * will be used exactly and an incomplete pattern may be used for the final waveform.
+     *
+     * \see triangularWavesRandomized()
+     * \since QGIS 3.24
+     */
+    QgsGeometry triangularWaves( double wavelength, double amplitude, bool strictWavelength = false ) const;
+
+    /**
+     * Constructs randomized triangular waves along the boundary of the geometry, with the
+     * specified wavelength and amplitude ranges.
+     *
+     * The \a minimumWavelength and \a maximumWavelength arguments set the range for the randomized
+     * wavelength. This is evaluated for each individual triangular waveform created along the geometry
+     * boundaries, so the resultant geometry will consist of many different wavelengths.
+     *
+     * Similarly, the \a minimumAmplitude and \a maximumAmplitude arguments define the range for the
+     * randomized amplitude of the triangular components. Randomized amplitude values will be calculated
+     * individually for triangles placed on each either side of the input geometry boundaries.
+     *
+     * Optionally, a specific random \a seed can be used when generating points. If \a seed
+     * is 0, then a completely random sequence of points will be generated.
+     *
+     * \see triangularWaves()
+     * \since QGIS 3.24
+     */
+    QgsGeometry triangularWavesRandomized( double minimumWavelength, double maximumWavelength, double minimumAmplitude, double maximumAmplitude, unsigned long seed = 0 ) const;
+
+    /**
+     * Constructs square waves along the boundary of the geometry, with the
+     * specified \a wavelength and \a amplitude.
+     *
+     * By default the \a wavelength argument is treated as a "maximum wavelength", where the actual
+     * wavelength will be dynamically adjusted so that an exact number of square waves are created
+     * along the boundaries of the geometry. If \a strictWavelength is set to TRUE then the \a wavelength
+     * will be used exactly and an incomplete pattern may be used for the final waveform.
+     *
+     * \see squareWavesRandomized()
+     * \since QGIS 3.24
+     */
+    QgsGeometry squareWaves( double wavelength, double amplitude, bool strictWavelength = false ) const;
+
+    /**
+     * Constructs randomized square waves along the boundary of the geometry, with the
+     * specified wavelength and amplitude ranges.
+     *
+     * The \a minimumWavelength and \a maximumWavelength arguments set the range for the randomized
+     * wavelength. This is evaluated for each individual square waveform created along the geometry
+     * boundaries, so the resultant geometry will consist of many different wavelengths.
+     *
+     * Similarly, the \a minimumAmplitude and \a maximumAmplitude arguments define the range for the
+     * randomized amplitude of the square components. Randomized amplitude values will be calculated
+     * individually for squares placed on each either side of the input geometry boundaries.
+     *
+     * Optionally, a specific random \a seed can be used when generating points. If \a seed
+     * is 0, then a completely random sequence of points will be generated.
+     *
+     * \see squareWaves()
+     * \since QGIS 3.24
+     */
+    QgsGeometry squareWavesRandomized( double minimumWavelength, double maximumWavelength, double minimumAmplitude, double maximumAmplitude, unsigned long seed = 0 ) const;
+
+    /**
+     * Constructs rounded (sine-like) waves along the boundary of the geometry, with the
+     * specified \a wavelength and \a amplitude.
+     *
+     * By default the \a wavelength argument is treated as a "maximum wavelength", where the actual
+     * wavelength will be dynamically adjusted so that an exact number of waves are created
+     * along the boundaries of the geometry. If \a strictWavelength is set to TRUE then the \a wavelength
+     * will be used exactly and an incomplete pattern may be used for the final waveform.
+     *
+     * \see roundWavesRandomized()
+     * \since QGIS 3.24
+     */
+    QgsGeometry roundWaves( double wavelength, double amplitude, bool strictWavelength = false ) const;
+
+    /**
+     * Constructs randomized rounded (sine-like) waves along the boundary of the geometry, with the
+     * specified wavelength and amplitude ranges.
+     *
+     * The \a minimumWavelength and \a maximumWavelength arguments set the range for the randomized
+     * wavelength. This is evaluated for each individual waveform created along the geometry
+     * boundaries, so the resultant geometry will consist of many different wavelengths.
+     *
+     * Similarly, the \a minimumAmplitude and \a maximumAmplitude arguments define the range for the
+     * randomized amplitude of the square components. Randomized amplitude values will be calculated
+     * individually for waves placed on each either side of the input geometry boundaries.
+     *
+     * Optionally, a specific random \a seed can be used when generating points. If \a seed
+     * is 0, then a completely random sequence of points will be generated.
+     *
+     * \see squareWaves()
+     * \since QGIS 3.24
+     */
+    QgsGeometry roundWavesRandomized( double minimumWavelength, double maximumWavelength, double minimumAmplitude, double maximumAmplitude, unsigned long seed = 0 ) const;
+
     /**
      * Returns a new geometry with all points or vertices snapped to the closest point of the grid.
      *