Analysis Report: Location Tab Issues in Remote Control Plugin

[kutaibaa-akraa]

---

@gzotti @alex-w @10110111

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:

1. 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
2. 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

[alex-w]

@kutaibaa-akraa sorry for late answer.

Please use script core.goHome(); for calling actionGo_Home_Globalaction.

I think solution 4.3 Client-Side Changes (Minimal) will enough for fixing problem here.

[kutaibaa-akraa]

@alex-w
Thank you for the feedback. Here are the essential clarifications:

---

The actionGo_Home_Global Button Already exists at the bottom toolbar (line with 16 buttons, including the home icon). I think No change needed.

---

The Client-Side Filtering vs Server-Side Fix :

The proposed client-side change (4.3) will NOT work without the server-side modification (4.1).

The loadRegionList() currently receives ALL 250+ regions from all planets. Adding a planet parameter to the client request has no effect until the server actually reads and uses that parameter.

Current server behavior:

// Always returns ALL regions regardless of any parameter
QStringList allRegions = StelApp::getInstance().getLocationMgr().getRegionNames();

Required server change:

// Read and use the planet parameter
QString planet = parameters.value("planet", "");
if (planet.isEmpty()) planet = StelApp::getInstance().getCore()->getCurrentLocation().planetName;
QStringList regionNames = StelApp::getInstance().getLocationMgr().getRegionNames(planet);

---

Required Changes

Change	Responsibility
1. Server-side fix (LocationService.cpp) – Read planet parameter and pass it to getRegionNames()	❗ Required 4.1
2. Client-side fix (api/location.js) – Send planet parameter in the request	I will handle this 4.3

The server-side change 4.1 is non-negotiable – the existing getRegionNames() already supports planet filtering, we just need to use it. The client-side change alone achieves nothing.

Your turn is to fix 4.1 solution
My turn 4.3 complementary solution

[alex-w]

Oh! I've committed a fix 4cb5db3

The line if (planet.isEmpty()) planet = StelApp::getInstance().getCore()->getCurrentLocation().planetName; is not needed here for backward compatibility

[alex-w]

Oops... a fix of typo - 0df9f44

[kutaibaa-akraa]

Current Behavior

GET /api/location/regionlist

→ Returns all regions from all planets (~250 entries)

New Behavior

Request	Response
GET /api/location/regionlist?planet=Mars	Only Mars regions (~16 entries)
GET /api/location/regionlist?planet=Earth	Only Earth regions (~24 entries)
GET /api/location/regionlist	Returns all regions (backward compatible, same as current)

This keeps 100% backward compatibility while enabling planet-specific region lists.
Look what @gzotti issued : The list should be filtered

[alex-w]

Done in master

[gzotti]

Oops, only seeing this now! Yes, the planet parameter can be added. And yes, for compatibility, without planet all regions should be returned.