Warning, file /education/kstars/kstars/skycomponents/skylabeler.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).

 /*
     SPDX-FileCopyrightText: 2007 James B. Bowlin <bowlin@mindspring.com>
     SPDX-License-Identifier: GPL-2.0-or-later
 */
 
 #pragma once
 
 #include "skylabel.h"
 
 #include <QFontMetricsF>
 #include <QList>
 #include <QVector>
 #include <QPainter>
 #include <QPicture>
 #include <QFont>
 
 class QString;
 class QPointF;
 class SkyMap;
 class Projector;
 struct LabelRun;
 
 typedef QList<LabelRun *> LabelRow;
 typedef QVector<LabelRow *> ScreenRows;
 
 /**
  *@class SkyLabeler
  * The purpose of this class is to prevent labels from overlapping.  We do this
  * by creating a virtual (lower Y-resolution) screen. Each "pixel" of this
  * screen essentially contains a boolean value telling us whether or not there
  * is an existing label covering at least part of that pixel.  Before you draw
  * a label, call mark( QPointF, QString ) of that label.  We will check to see
  * if it would overlap any existing label.  If there is overlap we return false.
  * If there is no overlap then we mark all the pixels that cover the new label
  * and return true.
  *
  * Since we need to check for overlap for every label every time it is
  * potentially drawn on the screen, efficiency is essential.  So instead of
  * having a 2-dimensional array of boolean values we use Run Length Encoding
  * and store the virtual array in a QVector of QLists.  Each element of the
  * vector, a LabelRow, corresponds to a horizontal strip of pixels on the actual
  * screen.  How many vertical pixels are in each strip is controlled by
  * m_yDensity.  The higher the density, the fewer vertical pixels per strip and
  * hence a larger number of strips are needed to cover the screen.  As
  * m_yDensity increases so does the density of the strips.
  *
  * The information in the X-dimension is completed run length encoded. A
  * consecutive run of pixels in one strip that are covered by one or more labels
  * is stored in a LabelRun object that merely stores the start pixel and the end
  * pixel.  A LabelRow is a list of LabelRun's stored in ascending order.  This
  * saves a lot of space over an explicit array and it also makes checking for
  * overlaps faster and even makes inserting new overlaps faster on average.
  *
  * Synopsis:
  *
  *   1) Create a new SkyLabeler
  *
  *   2) every time you want to draw a new screen, reset the labeler.
  *
  *   3) Either:
  *
  *   A) Call drawLabel() or drawOffsetLabel(), or
  *
  *   B) Call addLabel() or addOffsetLabel()
  *
  *  4) Call draw() if addLabel() or addOffsetLabel() were used.
  *
  *
  *
  * SkyLabeler works totally on a first come, first served basis which is almost
  * the direct opposite of a z-buffer where the objects drawn last are most
  * visible.  This is why the addLabel() and draw() routines were created.
  * They allow us to time-shift the drawing of labels and thus gives us control
  * over their priority.  The drawLabel() routines are still available but are
  * not being used.  The addLabel() routines adds a label to a specific buffer.
  * Each type of label has its own buffer which lets us control the font and
  * color as well as the priority.  The priority is now manually set in the
  * draw() routine by adjusting the order in which the various buffers get
  * drawn.
  *
  * Finally, even though this code was written to be very efficient, we might
  * want to take some care in how many labels we throw at it.  Sending it
  * a large number of overlapping labels can be wasteful. Also, if one type
  * of object floods it with labels early on then there may not be any room
  * left for other types of labels.  Therefore for some types of objects (stars)
  * we may want to have a zoom dependent label threshold magnitude just like
  * we have for drawing the stars themselves.  This would throw few labels
  * at the labeler when we are zoomed at and they would mostly overlap anyway
  * and it would give us more labels when the user is zoomed in and there
  * is more room for them.  The "b" key currently causes the labeler statistics
  * to be printed.  This may be useful in figuring out the best settings for
  * the magnitude limits.  It may even be possible to have KStars do some of
  * this throttling automatically but I haven't really thought about that
  * problem yet.
  *
  * -- James B. Bowlin  2007-08-02
  */
 class SkyLabeler
 {
   protected:
     SkyLabeler();
     SkyLabeler(SkyLabeler &skyLabler);
 
   public:
     enum label_t
     {
         STAR_LABEL,
         ASTEROID_LABEL,
         COMET_LABEL,
         PLANET_LABEL,
         JUPITER_MOON_LABEL,
         SATURN_MOON_LABEL,
         DEEP_SKY_LABEL,
         CONSTEL_NAME_LABEL,
         SATELLITE_LABEL,
         RUDE_LABEL, ///Rude labels block other labels FIXME: find a better solution
         NUM_LABEL_TYPES
     };
 
     //----- Static Methods ----------------------------------------------//
 
     static SkyLabeler *Instance();
 
     /**
          * @short returns the zoom dependent label offset.  This is used in this
          * class and in SkyObject.  It is important that the offsets be the same
          * so highlighted labels are always drawn exactly on top of the normally
          * drawn labels.
          */
     static double ZoomOffset();
 
     /**
          * @short static version of addLabel() below.
          */
     inline static void AddLabel(SkyObject *obj, label_t type) { pinstance->addLabel(obj, type); }
 
     //--------------------------------------------------------------------//
     ~SkyLabeler();
 
     /**
          * @short clears the virtual screen (if needed) and resizes the virtual
          * screen (if needed) to match skyMap.  A font must be specified which
          * is taken to be the average or normal font that will be used.  The
          * size of the horizontal strips will be (slightly) optimized for this
          * font.  We also adjust the font size in psky to smaller fonts if the
          * screen is zoomed out.  You can mimic this setting with the static
          * method SkyLabeler::setZoomFont( psky ).
          */
     void reset(SkyMap *skyMap);
 
 /**
          * @short KStars Lite version of the function above
          */
 #ifdef KSTARS_LITE
     void reset();
 #endif
 
     /**
          * @short Draws labels using the given painter
          * @param p the painter to draw labels with
          */
     void draw(QPainter &p);
 
     //----- Font Setting -----//
 
     /**
          * @short adjusts the font in psky to be smaller if we are zoomed out.
          */
     void setZoomFont();
 
     /**
          * @short sets the pen used for drawing labels on the sky.
          */
     void setPen(const QPen &pen);
 
     /**
          * @short tells the labeler the font you will be using so it can figure
          * out the height and width of the labels.  Also sets this font in the
          * psky since this is almost always what is wanted.
          */
     void setFont(const QFont &font);
 
     /**
          * @short decreases the size of the font in psky and in the SkyLabeler
          * by the delta points.  Negative deltas will increase the font size.
          */
     void shrinkFont(int delta);
 
     /**
          * @short sets the font in SkyLabeler and in psky to the font psky
          * had originally when reset() was called.  Used by ConstellationNames.
          */
     void useStdFont();
 
     /**
          * @short sets the font in SkyLabeler and in psky back to the zoom
          * dependent value that was set in reset().  Also used in
          * ConstellationLines.
          */
     void resetFont();
 
     /**
          * @short returns the fontMetricsF we have already created.
          */
     QFontMetricsF &fontMetrics() { return m_fontMetrics; }
 
     //----- Drawing/Adding Labels -----//
 
     /**
          *@short sets four margins for help in keeping labels entirely on the
          * screen.
          */
     void getMargins(const QString &text, float *left, float *right, float *top, float *bot);
 
     /**
          * @short Tries to draw the text at the position and angle specified. If
          * the label would overlap an existing label it is not drawn and we
          * return false, otherwise the label is drawn, its position is marked
          * and we return true.
          */
     bool drawGuideLabel(QPointF &o, const QString &text, double angle);
 
     /**
          * @short Tries to draw a label for an object.
          * @param obj the object to draw the label for
          * @param _p the position of that object
          * @return true if the label was drawn
          * //FIXME: should this just take an object pointer and do its own projection?
          *
          * \p padding_factor is the factor by which the real label size is scaled
          */
     bool drawNameLabel(SkyObject *obj, const QPointF &_p, const qreal padding_factor = 1);
 
     /**
          *@short draw the object's name label on the map, without checking for
          *overlap with other labels.
          *@param obj reference to the QPainter on which to draw (either the sky pixmap or printer device)
          *@param _p The screen position for the label (in pixels; typically as found by SkyMap::toScreen())
          */
     void drawRudeNameLabel(SkyObject *obj, const QPointF &_p);
 
     /**
          * @short queues the label in the "type" buffer for later drawing.
          */
     void addLabel(SkyObject *obj, label_t type);
 
 #ifdef KSTARS_LITE
     /**
          * @short queues the label in the "type" buffer for later drawing. Doesn't calculate the position of
          * SkyObject but uses pos as a position of label.
          */
     void addLabel(SkyObject *obj, QPointF pos, label_t type);
 #endif
     /**
          *@short draws the labels stored in all the buffers.  You can change the
          * priority by editing the .cpp file and changing the order in which
          * buffers are drawn.  You can also change the fonts and colors there
          * too.
          */
     void drawQueuedLabels();
 
     /**
          * @short a convenience routine that draws all the labels from a single
          * buffer. Currently this is only called from within draw() above.
          */
     void drawQueuedLabelsType(SkyLabeler::label_t type);
 
     //----- Marking Regions -----//
 
     /**
          * @short tells the labeler the location and text of a label you want
          * to draw.  Returns true if there is room for the label and returns
          * false otherwise.  If it returns true, the location of the label is
          * marked on the virtual screen so future labels won't overlap it.
          *
          * It is usually easier to use drawLabel() or drawLabelOffest() instead
          * which both call mark() internally.
          *
          * \p padding_factor is the factor by which the real label size is
          * scaled
          */
     bool markText(const QPointF &p, const QString &text, qreal padding_factor = 1);
 
     /**
          * @short Works just like markText() above but for an arbitrary
          * rectangular region bounded by top, bot, left, and right.
          */
     bool markRegion(qreal left, qreal right, qreal top, qreal bot);
 
     //----- Diagnostics and Information -----//
 
     /**
          * @short diagnostic. the *percentage* of pixels that have been filled.
          * Expect return values between 0.0 and 100.0.  A fillRatio above 20
          * is pretty busy and crowded.  I think a fillRatio of about 10 looks
          * good.  The fillRatio will be lowered of the screen is zoomed out
          * so are big blank spaces around the celestial sphere.
          */
     float fillRatio();
 
     /**
          * @short diagnostic, the number of times mark() returned true divided by
          * the total number of times mark was called multiplied by 100.  Expect
          * return values between 0.0 an 100.  A hit ratio of 100 means no labels
          * would have overlapped.  A ratio of zero means no labels got drawn
          * (which should never happen).  A hitRatio around 50 might be a good
          * target to shoot for.  Expect it to be lower when fully zoomed out and
          * higher when zoomed in.
          */
     float hitRatio();
 
     /**
          * @short diagnostic, prints some brief statistics to the console.
          * Currently this is connected to the "b" key in SkyMapEvents.
          */
     void printInfo();
 
     inline QFont stdFont() { return m_stdFont; }
     inline QFont skyFont() { return m_skyFont; }
 #ifdef KSTARS_LITE
     inline QFont drawFont() { return m_drawFont; }
 #endif
 
     int hits() { return m_hits; }
     int marks() { return m_marks; }
 
   private:
     ScreenRows screenRows;
     int m_maxX { 0 };
     int m_maxY { 0 };
     int m_size { 0 };
     /// When to merge two adjacent regions
     int m_minDeltaX { 30 };
     int m_marks { 0 };
     int m_hits { 0 };
     int m_misses { 0 };
     int m_elements { 0 };
     int m_errors { 0 };
     qreal m_yScale { 0 };
     double m_offset { 0 };
     QFont m_stdFont, m_skyFont;
     QFontMetricsF m_fontMetrics;
 //In KStars Lite this font should be used wherever font of m_p was changed or used
 #ifdef KSTARS_LITE
     QFont m_drawFont;
 #endif
     QPainter m_p;
     QPicture m_picture;
     QVector<LabelList> labelList;
     const Projector *m_proj { nullptr };
     static SkyLabeler *pinstance;
 };