Remote Control Plugin : Dynamic Sky Culture Explorer (index.html : tab_skyculture)

[kutaibaa-akraa]

Feature: Dynamic Sky Culture Explorer with Multi-Panel Data Visualization

Author: @kutaibaa-akraa
Date: 2026-04-07
Type: UI Enhancement / New Feature
Related PR: #4813 (Remote Control Interface)
Stellarium: v25.4

---

Overview

This feature replaces the static constellation dropdown in tab_skyculture with a dynamic, multi-panel explorer. The interface now displays constellations, asterisms, zodiac signs, lunar mansions, and notable stars as interactive button grids, parsed directly from each culture's index.json file via the API endpoint /api/view/skyculturedescription/index.json.

---

Console Discovery Method

The following console command was used to verify data accessibility and explore the structure of different sky cultures:

fetch('/api/view/skyculturedescription/index.json')
    .then(r => r.json())
    .then(data => {
        console.log('Culture ID:', data.id);
        console.log('Constellations:', data.constellations?.length || 0);
        console.log('Asterisms:', data.asterisms?.length || 0);
        console.log('Zodiac:', data.zodiac?.names?.length || 0);
        console.log('Lunar Mansions:', data.lunar_system?.names?.length || 0);
        console.log('Star Names:', Object.keys(data.common_names || {}).length);
    });

This confirmed that the API successfully serves index.json for any selected sky culture.

---

Data Statistics by Culture

Below is the complete dataset collected from testing 56 sky cultures in Stellarium 25.4. The data shows significant variation in how each culture organizes its astronomical knowledge.

Culture	ID	Constellations	Asterisms	Zodiac	Lunar	Star Names
Anutan	anutan	11	0	0	0	21
Arabic (Al-Sufi)	arabic_al-sufi	51	140	12	28	1024
Arabic (Arabian Peninsula)	arabic_arabian_peninsula	45	0	0	28	63
Arabic (Indigenous)	arabic_indigenous	118	34	0	28	15
Aztec	aztec	5	0	0	0	0
Babylonian (MUL.APIN)	babylonian_mulapin	58	0	0	0	22
Babylonian (Seleucid)	babylonian_seleucid	60	0	12	0	104
Balinese	balinese	31	0	0	0	2
Belarusian	belarusian	20	0	0	0	2
Boorong	boorong	29	0	0	0	30
Chinese	chinese	318	0	0	28	3072
Chinese Chenzhuo (3rd Century)	chinese_chenzhuo	317	0	0	28	187
Chinese Song Dynasty	chinese_song_dynasty	339	0	0	28	222
Egyptian (Dendera)	egyptian_dendera	36	0	0	0	14
Greek (Almagest)	greek_almagest	49	0	12	0	1039
Greek (Dante)	greek_dante	30	0	12	0	15
Greek (Farnese + Almagest)	greek_farnese	51	0	12	0	8
Greek (Leiden Aratea)	greek_leidenAratea	50	0	12	0	15
Hawaiian Starlines	hawaiian_starlines	13	0	0	0	70
Indian (Nakshatras)	indian_nakshatras	28	0	0	28	0
Indian Vedic	indian	49	28	12	28	39
Inuit	inuit	14	0	0	0	9
Japanese Yasui Map	japanese_moon_stations	28	0	0	0	0
Kamilaroi/Euahlayi	kamilaroi	13	0	0	0	0
Khoikhoi and San	khoi-san	6	0	0	0	12
Korean	korean	272	0	0	0	53
Lokono	lokono	11	0	0	0	7
Macedonian	macedonian	19	0	0	0	2
Maori	maori	6	0	0	0	32
Modern	modern	88	81	12	0	660
Modern (Chinese)	modern_chinese	88	311	0	0	3072
Modern (H.A. Rey)	modern_rey	170	8	0	0	36
Modern (IAU)	modern_iau	88	0	0	0	625
Modern (Journey to the West)	modern_journey_to_the_west	88	0	0	0	0
Modern (O. Hlad)	modern_hlad	88	0	0	0	237
Modern (Sky & Telescope)	modern_st	88	0	0	0	237
Mongolian	mongolian	4	0	0	0	20
Navajo	navajo	8	0	0	0	0
Norse	norse	6	0	0	0	3
Norse (Edda)	norse_edda	19	0	0	0	0
Northern Andes	northern_andes	5	3	0	0	0
Romanian	romanian	39	0	0	0	229
Ruanui (Tahiti)	ruanui_sky_tahiti_and_society_islands	19	0	0	0	71
Russian (Siberian)	russian_siberian	3	0	0	0	2
Sami	sami	10	0	0	0	0
Samoan	samoan	14	0	0	0	17
Sardinian	sardinian	12	0	0	0	6
Seri	seri	15	0	0	0	20
Tibetan	tibetan	18	27	12	27	0
Tikuna	tikuna	4	0	0	0	0
Tongan	tongan	11	0	0	0	11
Tukano	tukano	11	0	0	0	0
Tupi-Guarani	tupi	7	0	0	0	1
Vanuatu (Netwar)	vanuatu_netwar	10	0	0	0	9
Xhosa	xhosa	5	0	0	0	2
Zulu	zulu	5	0	0	0	11

---

Technical Implementation

New Files:

• webroot/js/ui/skyculture.js - Main module for data extraction and rendering
• webroot/js/stellarium-utils.js - Shared utilities (navigation, isolation, FOV)

Modified Files:

• webroot/index.html - New 5-panel layout for tab_skyculture
• webroot/gamepad.css - Styles for .pattern-btn and .patterns-buttons-grid

Key API Used:

• GET /api/view/skyculturedescription/index.json - Serves any file from current culture folder

---

Discussion Points

What Works

• Dynamic parsing of all 56 tested cultures
• Automatic panel visibility based on data availability
• Constellation isolation with state preservation (FOV, lines, boundaries, labels, art)
• Centering on asterisms, zodiac signs, lunar mansions, and stars

Open Questions

1. Performance with large datasets - Chinese culture has 3072star names. Do we need pagination or search/filter before merging?

2. Star name table - Current implementation uses simple buttons. Should we implement a sortable table with HIP catalog numbers and coordinates? This would require additional API calls to /api/objects/info.

3. Asterism vs Constellation - Some cultures have both. Current UI shows them in separate panels. Is this the right approach?

4. Translation handling - Star names and cultural terms need proper i18n. Currently using English names where available, falling back to native.

5. State synchronization - When user selects a constellation in the main Stellarium UI, should the corresponding button highlight automatically? This would require listening to stelPropertyChanged events.

6. Fallback behavior - For cultures without index.json, we default to 88 IAU constellations. This works for modern variants but may not be ideal for non-Western cultures. Alternative?

---

Files Modified/Created

File	Type	Description
webroot/js/ui/skyculture.js	New	Data extraction and panel rendering
webroot/js/stellarium-utils.js	New	Navigation, isolation, FOV utilities
webroot/index.html	Modified	5-panel layout for sky culture tab
webroot/gamepad.css	Modified	Button grid styles
webroot/tablet7in.html	Modified	Responsive adjustments

---

Next Steps & Discussion

1. Enhanced Star Names Table

   • Currently displaying star names as simple buttons
   • Proposed: Rich HTML table with columns for:
     • English name
     • Native name (original language script)
     • Transliteration / Pronunciation
     • Hipparcos catalog number
     • Right Ascension / Declination
   • Each row clickable to center on the star

2. Search/Filter Functionality

   • Add search input to filter long lists (e.g., 317 constellations in Chinese culture)
   • Real-time filtering as user types

3. Tooltips with Additional Information

   • Hover tooltips showing native names, pronunciations, cultural context
   • For stars: magnitude, catalog numbers

I am actively working on enriching this interface to become a comprehensive cultural astronomy explorer. The current implementation successfully demonstrates:

• Dynamic JSON parsing from 50+ sky cultures
• Responsive multi-panel layout
• Integration with Stellarium's core APIs

This feature is ready for review and testing. Feedback welcome on:

• UI layout and panel organization
• Performance on lower-end devices with large datasets
• Additional data fields worth displaying

---

Figuer: new skycultrue tab UI with 5 new panels

[gzotti]

OMG, 26.2 will be quite something! We are just past 26.1, and you create the next big thing. I had wanted the single-select buttons for a long time! There is just no space on the main GUI...
But as before, please formulate this as Pull Request.

Regarding state sync: Yes please, and take note that you may have several web clients (e.g. sitting operator on desktop PC, second presenter with tablet) operating one Stellarium concurrently.

[kutaibaa-akraa]

Correction: Fixing Star Count for Arabic (Al-Sufi) Culture

@gzotti

Thank you for your feedback and encouragement. I would like to clarify an issue I encountered with the star count calculation for the Arabic (Al-Sufi) culture and how it was resolved.

The Problem

When analyzing the index.json file for the Arabic (Al-Sufi) culture, I discovered that the previously reported star count (1812) was significantly inaccurate.

Root Cause

In the index.json file, star data in the common_names array is structured as follows:

"HIP 68702": [
    {"english": "Cen_36", "native": "قنط_٣٦"},
    {"english": "The star on the knee of the left [front] leg", "native": "الذي على ركبة الرجل اليسرى، وهو على الركبة من اليد اليسرى"},
    {"english": "Hadari", "native": "حضار", "pronounce": "Hadārī"}
]

These three entries represent a single star (one HIP 68702). However, the previous extraction algorithm treated each array entry as a separate star, resulting in:

• Significant inflation of the star count
• Duplicate buttons for the same star
• Inaccurate statistics

The Solution

The extractStarNames function was modified to work as follows:

1. Name Aggregation: All entries sharing the same HIP identifier are grouped into a single object
2. Primary Name Selection: The first English name is used as the primary name for search and centering
3. Display Name Formatting: Multiple English names are combined into a single button with proper formatting:
   • Single name: Name1
   • Two names: Name1 - Name2
   • Three or more names: Name1 - Name2 (Name3 / Name4)
4. Search Name Separation: searchName (primary name) is stored separately for centering, while the combined name appears only on the button

Example

HIP ID	English Names	Display Button	Search Name
HIP 68702	Cen_36, The star on the knee..., Hadari	Cen_36 - The star on the knee of the left [front] leg (Hadari)	Cen_36

Final Results

Metric	Before Fix	After Fix
Star count for Arabic (Al-Sufi) culture	1812 (incorrect)	1024 (correct)
Buttons per star	3 buttons for same star	1 button per star
Counter accuracy	Inaccurate	Accurate

Count Badges for All Sections

Additionally, count badges have been added next to each section title:

Section	Counter	Note
Constellations	Number of constellations	Based on constellations.length
Asterisms	Number of asterisms	Based on asterisms.length
Zodiac Signs	Number of zodiac signs	Typically 12, culture-dependent
Lunar Mansions	Number of lunar mansions	Typically 28, culture-dependent
Notable Stars	Number of unique stars	Now corrected

Summary

• The previous count (1812) represented the total star name entries (multiple names per star), not the number of unique stars
• The current count (1024) represents the number of unique stars in the Arabic (Al-Sufi) culture
• Each star now appears as a single button with all its names combined
• The centering function works correctly using the primary name
• The star counter now reflects the actual number of unique stars

---

Note: Regarding state sync (synchronizing state across multiple browsers), I will postpone this work for now and return to it in a later phase.

---

Attached is a screenshot demonstrating the fixed Sky Culture tab with Arabic (Al-Sufi) culture. Count badges are shown correctly, and star names are properly combined (e.g., "Cen_36 - The star on the knee... (Hadari)"). All buttons work as expected.

*Duplicate star entries have been removed; counter now shows 1024 unique stars (down from 1812).*

[gzotti]

While I had no time so far (give us a weekend after a release!), do we ever show star counts? (Not more than 1 button per star still sounds good.)

[gzotti]

If possible, can you present the available skycultures sorted by geographic region in a similar way as was changed in V26.1? and more challenging, see the map interface in 26.1. The Skycultures will be enriched with a territory.geojson file that can highlight each culture on a map. Is there a way to also show this in a panel? (Not required for this time, but would be great at least later this year!)