Analysis Report: Location Tab Issues in Remote Control Plugin #5058

kutaibaa-akraa · 2026-07-26T18:15:01Z

kutaibaa-akraa
Jul 26, 2026

Report ID: RC-LOC-420-001
Date: July 26, 2026
Author: kutaibaa-akraa
Related PR: #4956 - Comprehensive Remote Control Enhancement

1. Executive Summary

The Location tab in the Stellarium Remote Control plugin has two issues that affect usability:

Region dropdown shows all regions for all planets – When a user selects Mars, the region dropdown still shows 250+ regions including Earth continents alongside Martian plains
No "Return to Default Location" functionality exposed via StelAction – Users cannot reset to their saved home location via the RC interface using the same method as the GUI

This report documents the root cause of both issues and proposes a server-side fix that requires no client-side filtering workarounds.

2. Problem Description

2.1 Issue 1: Region Dropdown Not Filtered by Planet

Observed Behavior:

When a user changes the planet from Earth to Mars (or any other celestial body), the Region dropdown continues to display all regions for all planets (~250 entries).

Expected Behavior:

The Region dropdown should display only regions relevant to the currently selected planet (e.g., 16 Martian regions for Mars, ~24 Earth regions for Earth).

Current API Response for GET /api/location/regionlist:

[
  {"name": "Northern Africa", "name_i18n": "Northern Africa"},
  {"name": "Western Asia", "name_i18n": "Western Asia"},
  {"name": "Aphrodite Terra", "name_i18n": "Aphrodite Terra"},
  {"name": "Ishtar Terra", "name_i18n": "Ishtar Terra"},
  {"name": "Ocean of Storms", "name_i18n": "Ocean of Storms"},
  {"name": "Acidalia Planitia", "name_i18n": "Acidalia Planitia"},
  ...
]

All 250+ regions from all planets are returned as a single flat array with no planet identifier.

Desired API Response for GET /api/location/regionlist?planet=Mars:

[
  {"name": "Acidalia Planitia", "name_i18n": "Acidalia Planitia"},
  {"name": "Amazonis Planitia", "name_i18n": "Amazonis Planitia"},
  {"name": "Arcadia Planitia", "name_i18n": "Arcadia Planitia"},
  {"name": "Argyre Planitia", "name_i18n": "Argyre Planitia"},
  {"name": "Chryse Planitia", "name_i18n": "Chryse Planitia"},
  {"name": "Elysium Planitia", "name_i18n": "Elysium Planitia"},
  {"name": "Hellas Planitia", "name_i18n": "Hellas Planitia"},
  {"name": "Isidis Planitia", "name_i18n": "Isidis Planitia"},
  {"name": "Utopia Planitia", "name_i18n": "Utopia Planitia"},
  {"name": "Aonia Terra", "name_i18n": "Aonia Terra"},
  {"name": "Arabia Terra", "name_i18n": "Arabia Terra"},
  {"name": "Terra Cimmeria", "name_i18n": "Terra Cimmeria"},
  {"name": "Terra Sabaea", "name_i18n": "Terra Sabaea"},
  {"name": "Vastitas Borealis", "name_i18n": "Vastitas Borealis"},
  {"name": "Tharsis", "name_i18n": "Tharsis"},
  {"name": "Planum Boreum", "name_i18n": "Planum Boreum"}
]

2.2 Issue 2: No "Return to Default Location" via StelAction

The regular Stellarium GUI (Location window) has a "Return to default location" button that calls StelCore::returnToDefaultLocation(). However:

StelCore::returnToDefaultLocation() is not exposed as a StelAction
The existing actionGo_Home_Global works via the StelAction API, but this is a general "go home" action that duplicates behavior with additional landscape management
LandscapeMgr.defaultLandscapeID only returns the landscape (e.g., "guereins") but not the location coordinates

3. Root Cause Analysis

3.1 Region Filtering – The Server Already Has the Logic

The core filtering logic already exists in StelLocationMgr::getRegionNames():

stellarium/src/core/StelLocationMgr.cpp

Line 1476 in f24728c

QStringList StelLocationMgr::getRegionNames(const QString& planet) const

// StelLocationMgr.cpp - getRegionNames() already supports planet filtering!
QStringList StelLocationMgr::getRegionNames(const QString& planet) const
{
    QStringList allregions;
    if (planet.isEmpty())
    {
        // Returns ALL regions for ALL planets
        for (int i=0; i<regions.size(); i++)
            allregions.append(regions.at(i).regionName);
    }
    else
    {
        // Filters by planet!
        for (int i=0; i<regions.size(); i++)
        {
            if (planet.contains(regions.at(i).planet, Qt::CaseInsensitive) && 
                !planet.contains("Observer", Qt::CaseInsensitive))
                allregions.append(regions.at(i).regionName);
        }
    }
    return allregions;
}

The problem is in LocationService.cpp – it calls getRegionNames() with no argument (implicitly empty string) instead of the current planet:

stellarium/plugins/RemoteControl/src/LocationService.cpp

Line 59 in f24728c

const StelTranslator& trans = *StelTranslator::globalTranslator;

// LocationService.cpp - CURRENT CODE (version 24.4)
else if(operation == "regionlist")
{
    const StelTranslator& trans = *StelTranslator::globalTranslator;
    // ❌ No argument = empty string = all regions for all planets
    QStringList allRegions = StelApp::getInstance().getLocationMgr().getRegionNames();
    QJsonArray list;
    for (const auto &str : std::as_const(allRegions))
    {
        QJsonObject obj;
        obj.insert("name",str);
        obj.insert("name_i18n",trans.qtranslate(str));
        list.append(obj);
    }
    response.writeJSON(QJsonDocument(list));
}

3.2 Why Client-Side Filtering Is Not the Solution

While we could filter regions in JavaScript based on naming patterns (e.g., "Planitia" = Mars, "Sea of" = Moon), this approach is:

Fragile – Relies on string matching that may miss new or unusual region names
Incomplete – Cannot distinguish between Earth's "Sea of..." regions and the Moon's
Unmaintainable – Requires updates whenever new planets or region types are added
The server knows the answer; the client should not have to guess

4. Proposed Solution: Server-Side Fix

4.1 Modify `LocationService.cpp`

File: plugins/RemoteControl/src/LocationService.cpp

Proposed fix:

else if(operation == "regionlist")
{
    const StelTranslator& trans = *StelTranslator::globalTranslator;

    // Read optional planet parameter from query string
    QString planet = QString::fromUtf8(parameters.value("planet", ""));
    
    // If no planet specified, use the currently active planet
    if (planet.isEmpty())
    {
        planet = StelApp::getInstance().getCore()->getCurrentLocation().planetName;
    }
    
    // Handle "Observer" special case - no regions for this type
    if (planet.contains("Observer", Qt::CaseInsensitive))
    {
        response.writeJSON(QJsonDocument(QJsonArray()));
        return;
    }
    
    // Use the existing getRegionNames() with planet filtering
    QStringList regionNames = StelApp::getInstance().getLocationMgr().getRegionNames(planet);
    
    // Build response (same format as before)
    QJsonArray regionsArray;
    for (const auto& name : regionNames)
    {
        QJsonObject regionObj;
        regionObj.insert("name", name);
        regionObj.insert("name_i18n", trans.qtranslate(name));
        regionsArray.append(regionObj);
    }
    
    response.writeJSON(QJsonDocument(regionsArray));
}

4.2 API Behavior After Fix

Request	Response	Count
`GET /api/location/regionlist`	Regions for current planet	~24 (Earth)
`GET /api/location/regionlist?planet=Earth`	Earth regions only	~24
`GET /api/location/regionlist?planet=Mars`	Mars regions only	~16
`GET /api/location/regionlist?planet=Moon`	Moon regions only	~50
`GET /api/location/regionlist?planet=Venus`	Venus regions only	~80

4.3 Client-Side Changes (Minimal)

With the server fix, the client code becomes trivially simple – no filtering needed:

// api/location.js - loadRegionList()
loadRegionList: function(callback) {
    $.ajax({
        url: '/api/location/regionlist',
        method: 'GET',
        data: { planet: lastPlanet || 'Earth' },
        dataType: 'json',
        success: function(data) {
            // Data is already filtered by the server!
            callback(data);
        },
        error: function() { callback([]); }
    });
}

When the user changes the planet, we simply reload the region list with the new planet parameter.

4.4 The `getRegionNames()` Function in StelLocationMgr

The function is declared in StelLocationMgr.hpp with an optional parameter:

stellarium/src/core/StelLocationMgr.hpp

Line 111 in f24728c

QStringList getRegionNames(const QString& planet = "") const;

And implemented in StelLocationMgr.cpp:

stellarium/src/core/StelLocationMgr.cpp

Line 1476 in f24728c

QStringList StelLocationMgr::getRegionNames(const QString& planet) const

// StelLocationMgr.cpp - lines 1476-1493
QStringList StelLocationMgr::getRegionNames(const QString& planet) const
{
    QStringList allregions;
    if (planet.isEmpty())
    {
        for (int i=0; i<regions.size(); i++)
            allregions.append(regions.at(i).regionName);
    }
    else
    {
        for (int i=0; i<regions.size(); i++)
        {
            if (planet.contains(regions.at(i).planet, Qt::CaseInsensitive) && 
                !planet.contains("Observer", Qt::CaseInsensitive))
                allregions.append(regions.at(i).regionName);
        }
    }
    return allregions;
}

4.5 The `GeoRegion` Structure

The structure that holds region data includes the planet field:

stellarium/src/core/StelLocationMgr.hpp

Line 36 in f24728c

typedef struct

// StelLocationMgr.hpp - lines 36-41
typedef struct
{
    int code;
    QString regionName;
    QString countries;
    QString planet;  // Contains the planet name
} GeoRegion;

5. Return to Default Location

5.1 Current State

Method	Status
`actionGo_Home_Global` (StelAction)	Works
`StelCore.returnToDefaultLocation()` (StelAction)	Not exposed
`LandscapeMgr.defaultLandscapeID` (StelProperty)	Returns landscape only

5.2 Analysis from Source Code

In StelCore.cpp, returnToDefaultLocation() exists:

stellarium/src/core/StelCore.cpp

Line 1177 in f24728c

void StelCore::returnToDefaultLocation()

// StelCore.cpp - lines 1177-1191
void StelCore::returnToDefaultLocation()
{
    StelLocationMgr& locationMgr = StelApp::getInstance().getLocationMgr();
    StelLocation loc = locationMgr.locationForString(defaultLocationID);
    if (loc.isValid())
        moveObserverTo(loc, 1., 2.);
    else
    {
        qCritical() << "StelCore::returnToDefaultLocation: " << defaultLocationID << ": returned Location " <<
                       loc.serializeToLine().replace('\t', '|') <<
                       "is invalid. Store an entry from the locations list as default location.";
        // Move to last resort location
        moveObserverTo(locationMgr.getLastResortLocation(), 1., 2.);
    }
}

And in StelCore.hpp, the function is declared as a public slot:

stellarium/src/core/StelCore.hpp

Line 479 in f24728c

void returnToDefaultLocation();

// StelCore.hpp - line 479
void returnToDefaultLocation();

The returnToHome() function also exists:

stellarium/src/core/StelCore.cpp

Line 1193 in f24728c

void StelCore::returnToHome()

// StelCore.cpp - lines 1193-1226
void StelCore :: returnToHome()
{
    // Using returnToDefaultLocation() and getCurrentLocation() can cause issues
    StelLocationMgr& locationMgr = StelApp::getInstance().getLocationMgr();
    StelLocation loc;
    QSettings* conf = StelApp::getInstance().getSettings();
    if (defaultLocationID == "auto")
    {
        locationMgr.locationFromIP();
        loc = locationMgr.getLastResortLocation();
    }
    else
        loc = locationMgr.locationForString(defaultLocationID);

    if (loc.isValid())
        moveObserverTo(loc, conf->value("navigation/return_home_duration", 0.).toDouble());
    else
        qWarning() << "Invalid location" << loc.serializeToLine();

    PlanetP p = GETSTELMODULE(SolarSystem)->searchByEnglishName(loc.planetName);

    LandscapeMgr* landscapeMgr = GETSTELMODULE(LandscapeMgr);
    landscapeMgr->setCurrentLandscapeID(landscapeMgr->getDefaultLandscapeID());
    landscapeMgr->setFlagAtmosphere(p->hasAtmosphere() && conf->value("landscape/flag_atmosphere", true).toBool());
    landscapeMgr->setFlagFog(p->hasAtmosphere() && conf->value("landscape/flag_fog", true).toBool());
    landscapeMgr->setFlagLandscape(!p->getEnglishName().contains("observer", Qt::CaseInsensitive) && 
                                    conf->value("landscape/flag_landscape", true).toBool());

    GETSTELMODULE(StelObjectMgr)->unSelect();

    StelMovementMgr* smmgr = getMovementMgr();
    smmgr->setViewDirectionJ2000(altAzToJ2000(smmgr->getInitViewingDirection(), StelCore::RefractionOff));
    smmgr->zoomTo(smmgr->getInitFov(), conf->value("navigation/return_fov_duration", 1.).toDouble());
}

In StelCore::init(), actionGo_Home_Global is registered:

stellarium/src/core/StelCore.cpp

Line 385 in f24728c

    
           actionsMgr->addAction("actionGo_Home_Global", movementGroup, N_("Go to home"), this, "returnToHome()", "Ctrl+H");

// StelCore.cpp - lines 385
actionsMgr->addAction("actionGo_Home_Global", movementGroup, N_("Go to home"), this, "returnToHome()", "Ctrl+H");

5.3 Recommendation

The existing actionGo_Home_Global is sufficient for the Remote Control interface. It provides the same functionality as the GUI's "Return to default location" button. No server-side changes are needed for this feature.

Note: returnToDefaultLocation() is not currently exposed via the StelAction API. If there is a need to expose it directly, it could be added to StelActionMgr in the same manner as actionGo_Home_Global.

The button in the RC interface can call:

actionApi.execute("actionGo_Home_Global");

6. Impact and Benefits

6.1 Immediate Benefits

Correct region display for all planets (Earth, Mars, Moon, Venus, Mercury, etc.)
Better user experience – no confusion from seeing irrelevant regions
Faster loading – smaller payload (16 regions vs 250+)
No client-side hacks – clean, maintainable code

6.2 Backward Compatibility

Fully compatible – the planet parameter is optional
Without the parameter, behavior defaults to current planet
Existing clients continue to work without modification

7. Implementation Checklist

Modify LocationService.cpp to read planet parameter
Pass planet to getRegionNames() instead of empty string
Update client-side api/location.js to send planet parameter (minimal change)
No client-side region manual filtering code needed
Test with all major planets (Earth, Mars, Moon, Venus, Mercury, Jupiter)

8. Files to Modify

File	Change
plugins/RemoteControl/src/LocationService.cpp	Add planet parameter support
webroot/js/api/location.js	Send planet parameter

9. Conclusion

The Region dropdown issue has a simple, one-file server-side fix that leverages existing infrastructure (getRegionNames() already supports planet filtering). No client-side workarounds are needed, and the fix is fully backward-compatible.

This is a server-side only change that requires no new API endpoints, no breaking changes, and minimal code modification.

The "Return to Default Location" functionality is already available through the existing actionGo_Home_Global StelAction.

10. References

Related Code Files

File	Purpose
StelLocationMgr.cpp	Contains `getRegionNames()` with planet filtering
StelLocationMgr.hpp	Declaration of `getRegionNames()` with optional parameter
LocationService.cpp	RC plugin endpoint for `/api/location/regionlist`
StelCore.cpp	Contains `returnToDefaultLocation()` and `returnToHome()`
StelCore.hpp	Declaration of location-related functions
RemoteControl.cpp	Registration of `actionGo_Home_Global`
api/location.js	Client-side location API module
ui/location.js	Client-side location UI module

Data Files

File	Purpose
`data/regions-geoscheme.tab`	Region definitions for all planets
`data/base_locations.bin.gz`	33,501 Earth locations
`data/iso3166.tab`	Country code mappings

Related PR: #4956 - Comprehensive Remote Control Enhancement

Navigation Menu

Uh oh!

Uh oh!

Analysis Report: Location Tab Issues in Remote Control Plugin #5058

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Uh oh!

Uh oh!

Analysis Report: Location Tab Issues in Remote Control Plugin #5058

Uh oh!

Uh oh!

kutaibaa-akraa Jul 26, 2026

1. Executive Summary

2. Problem Description

2.1 Issue 1: Region Dropdown Not Filtered by Planet

2.2 Issue 2: No "Return to Default Location" via StelAction

3. Root Cause Analysis

3.1 Region Filtering – The Server Already Has the Logic

3.2 Why Client-Side Filtering Is Not the Solution

4. Proposed Solution: Server-Side Fix

4.1 Modify LocationService.cpp

4.2 API Behavior After Fix

4.3 Client-Side Changes (Minimal)

4.4 The getRegionNames() Function in StelLocationMgr

4.5 The GeoRegion Structure

5. Return to Default Location

5.1 Current State

5.2 Analysis from Source Code

5.3 Recommendation

6. Impact and Benefits

6.1 Immediate Benefits

6.2 Backward Compatibility

7. Implementation Checklist

8. Files to Modify

9. Conclusion

10. References

Related Code Files

Data Files

Replies: 0 comments

kutaibaa-akraa
Jul 26, 2026

4.1 Modify `LocationService.cpp`

4.4 The `getRegionNames()` Function in StelLocationMgr

4.5 The `GeoRegion` Structure