diff --git a/docs/source/user_guide.rst b/docs/source/user_guide.rst index 6fe771fa0..af2945512 100644 --- a/docs/source/user_guide.rst +++ b/docs/source/user_guide.rst @@ -218,7 +218,9 @@ Press **SQUARE** to cycle through additional information for the objects on the .. image:: images/user_guide/object_list_02_docs.png -You can see a scrolling list of common names for each object. +You can see a scrolling list of common names for each object. The lists of objects that go +by name open with this view: Planets, Comets, and the star, double star, asterism, and +variable star catalogs (Str, Nam, SaA, SaR, SaM, RDS, WDS, TLK). .. image:: images/user_guide/object_list_03_docs.png diff --git a/python/PiFinder/catalogs.py b/python/PiFinder/catalogs.py index bae42010b..bef18950c 100644 --- a/python/PiFinder/catalogs.py +++ b/python/PiFinder/catalogs.py @@ -53,6 +53,22 @@ VALID_T9_DIGITS = "".join(KEYPAD_DIGIT_TO_CHARS.keys()) INVALID_T9_DIGITS_RE = re.compile(f"[^{VALID_T9_DIGITS}]") +# The object list display mode a catalog's list opens in (#408), by catalog +# code. The values name members of ui.object_list.DisplayModes. These catalogs +# open in NAME mode: their sequence is only a position in the list, and an +# observer knows the object by its name (Algol, RX Peg, Winter Triangle). All +# other catalogs open in LOCATE mode. The registry is in code, not in +# objects.db, because planets and comets are built at run time. +NAME_MODE_CATALOGS = frozenset( + {"PL", "CM", "Str", "Nam", "SaA", "SaR", "TLK", "SaM", "RDS", "WDS"} +) + + +def default_display_mode_for(catalog_code: str) -> str: + """The DisplayModes member name a list of this catalog opens in.""" + return "NAME" if catalog_code in NAME_MODE_CATALOGS else "LOCATE" + + # collection of all catalog-related classes # CatalogBase : just the CompositeObjects (imported from catalog_base) @@ -331,6 +347,11 @@ def is_selected(self): return False return self.catalog_code in self.catalog_filter.selected_catalogs + @property + def default_display_mode(self) -> str: + """The DisplayModes member name this catalog's object list opens in.""" + return default_display_mode_for(self.catalog_code) + def has(self, sequence: int, filtered=True): return sequence in self.filtered_objects_seq diff --git a/python/PiFinder/ui/object_list.py b/python/PiFinder/ui/object_list.py index b87ac0f2b..330e9d217 100644 --- a/python/PiFinder/ui/object_list.py +++ b/python/PiFinder/ui/object_list.py @@ -13,6 +13,7 @@ import functools from functools import cache import math as math +import re from PIL import Image, ImageChops from itertools import cycle @@ -27,7 +28,8 @@ from PiFinder import utils from PiFinder.composite_object import CompositeObject, MagnitudeObject from PiFinder.nearby import Nearby -from PiFinder.catalogs import CatalogState +from PiFinder.catalogs import CatalogState, default_display_mode_for +from PiFinder.designations import parse_designation from PiFinder.ui.ui_utils import ( TextLayouterScroll, name_deduplicate, @@ -66,6 +68,27 @@ class SortOrder(Enum): _NEARBY_INDEX_UNBUILT = object() +# PiFinder's own WDS listing ("WDS 4631") and the WDS coordinate designation +# ("WDS J00568+3830"). parse_designation reads neither: "wds" is not a +# catalog code alias. +_WDS_LISTING_RE = re.compile(r"wds\s*\d+", re.IGNORECASE) +_WDS_COORDINATE_RE = re.compile(r"wds\s*j", re.IGNORECASE) + + +def _name_group(name: str) -> int: + """ + Where a name goes in the NAME-mode text: 0 for a real name ("Mu And", + "h 1057", "HD 208526"), 1 for a PiFinder catalog designation ("SaM 25", + "M15", "WDS 4631"), 2 for a WDS coordinate designation. + """ + name = name.strip() + if _WDS_COORDINATE_RE.match(name): + return 2 + if _WDS_LISTING_RE.fullmatch(name) or parse_designation(name) is not None: + return 1 + return 0 + + def _sort_order_label(sort_order: "SortOrder") -> str: if sort_order == SortOrder.CATALOG_SEQUENCE: return _("Catalog") @@ -138,8 +161,7 @@ def __init__(self, *args, **kwargs) -> None: self._nearby_index_key: Any = _NEARBY_INDEX_UNBUILT # Init display mode defaults - self.mode_cycle = cycle(DisplayModes) - self.current_mode = next(self.mode_cycle) + self._init_display_mode() # Initialize sort default self.sort_cycle = cycle(SortOrder) @@ -212,6 +234,28 @@ def __init__(self, *args, **kwargs) -> None: self.refresh_object_list(force_update=True) self.nearby = Nearby(self.shared_state) + def _init_display_mode(self) -> None: + """ + Start in the default display mode of the list's catalog: NAME for + catalogs whose objects go by name (planets, stars, doubles), LOCATE + for the others and for lists that mix catalogs. The cycle is advanced + to that mode, so SQUARE goes on to the next mode in the usual order. + """ + start_mode = DisplayModes.LOCATE + if self.item_definition.get("objects") == "catalog": + catalog_code = self.item_definition.get("value", "") + catalog = self.catalogs.get_catalog_by_code(catalog_code) + start_mode = DisplayModes[ + catalog.default_display_mode + if catalog is not None + else default_display_mode_for(catalog_code) + ] + + self.mode_cycle = cycle(DisplayModes) + self.current_mode = next(self.mode_cycle) + while self.current_mode != start_mode: + self.current_mode = next(self.mode_cycle) + def refresh_object_list(self, force_update=False): """ Called whenever the object list might need to be updated. @@ -436,9 +480,16 @@ def _interpolate_color(self, mag, min_mag=9, max_mag=16): return int(255 + ((125 - 255) / (16 - 9)) * (mag - 9)) def create_name_text(self, obj: CompositeObject) -> str: + """ + The NAME-mode text: real names first, then PiFinder catalog + designations, then WDS coordinate designations. The names table + often puts designations first ("SaM 25, Mu And" on SaM 26); the + observer looks for the name. The order inside each group is kept, and + the row's own designation is left out. + """ dedups = name_deduplicate(obj.names, [f"{obj.catalog_code}{obj.sequence}"]) - result = ", ".join(dedups) - return result + # sorted() is stable, so each group keeps the names table's order. + return ", ".join(sorted(dedups, key=_name_group)) # Use 3-letter abbreviations for planets instead of PL1, PL2, etc. # Falls back to full name if planet is not in the dictionary. diff --git a/python/tests/test_object_list_display_mode.py b/python/tests/test_object_list_display_mode.py new file mode 100644 index 000000000..d0a54774b --- /dev/null +++ b/python/tests/test_object_list_display_mode.py @@ -0,0 +1,220 @@ +"""Tests for the object list's NAME mode (#408). + +A list of one catalog opens in its catalog's default display mode: NAME for +catalogs whose objects go by name (planets, comets, stars, doubles), LOCATE +for the others. SQUARE then cycles on from there in the usual order. Lists +that mix catalogs keep the LOCATE start. The NAME-mode text puts real names +before catalog designations. +""" + +import pytest + +from PiFinder.catalogs import ( + NAME_MODE_CATALOGS, + Catalog, + Catalogs, + PlanetCatalog, + default_display_mode_for, +) +from PiFinder.comet_catalog import CometCatalog +from PiFinder.composite_object import CompositeObject +from PiFinder.ui.object_list import DisplayModes, UIObjectList, _name_group + +NAME_MODE = ["PL", "CM", "Str", "Nam", "SaA", "SaR", "TLK", "SaM", "RDS", "WDS"] +LOCATE_MODE = [ + "M", + "NGC", + "IC", + "C", + "Col", + "Sh2", + "H", + "B", + "Abl", + "Arp", + "Ta2", + "Har", + "EGC", + "Lyn", + "OBS", +] + + +def _object_list(item_definition: dict, catalogs: Catalogs) -> UIObjectList: + """A UIObjectList with only what the display mode code uses. + + The full constructor needs a display, a config and shared state; the + display mode methods read only these attributes. + """ + module = UIObjectList.__new__(UIObjectList) + module.item_definition = item_definition + module.catalogs = catalogs + module.jump_input_display = False + module.last_item_index = 0 + module.update = lambda *args, **kwargs: None # key_square redraws + module._init_display_mode() + return module + + +@pytest.fixture +def catalogs() -> Catalogs: + return Catalogs([Catalog(code, code) for code in NAME_MODE + LOCATE_MODE]) + + +@pytest.mark.unit +def test_registry(): + assert NAME_MODE_CATALOGS == frozenset(NAME_MODE) + for code in NAME_MODE: + assert default_display_mode_for(code) == "NAME" + assert Catalog(code, code).default_display_mode == "NAME" + for code in LOCATE_MODE: + assert default_display_mode_for(code) == "LOCATE" + assert Catalog(code, code).default_display_mode == "LOCATE" + + +@pytest.mark.unit +def test_registry_values_are_display_modes(): + assert DisplayModes[default_display_mode_for("SaR")] is DisplayModes.NAME + assert DisplayModes[default_display_mode_for("NGC")] is DisplayModes.LOCATE + + +@pytest.mark.unit +def test_dynamic_catalogs_inherit_the_default(): + # Planets and comets are built at run time; their classes use the same + # registry as every other Catalog. + assert PlanetCatalog.default_display_mode is Catalog.default_display_mode + assert CometCatalog.default_display_mode is Catalog.default_display_mode + + +@pytest.mark.unit +@pytest.mark.parametrize("catalog_code", NAME_MODE) +def test_names_catalog_opens_in_name_mode(catalog_code, catalogs): + module = _object_list({"objects": "catalog", "value": catalog_code}, catalogs) + assert module.current_mode is DisplayModes.NAME + + +@pytest.mark.unit +@pytest.mark.parametrize("catalog_code", ["M", "NGC", "IC", "Col"]) +def test_deep_sky_catalog_opens_in_locate_mode(catalog_code, catalogs): + module = _object_list({"objects": "catalog", "value": catalog_code}, catalogs) + assert module.current_mode is DisplayModes.LOCATE + + +@pytest.mark.unit +def test_catalog_not_built_yet_uses_the_registry(): + # The comet catalog may be missing while it loads; the registry decides. + module = _object_list({"objects": "catalog", "value": "CM"}, Catalogs([])) + assert module.current_mode is DisplayModes.NAME + + +@pytest.mark.unit +def test_square_cycles_on_from_a_name_start(catalogs): + module = _object_list({"objects": "catalog", "value": "SaR"}, catalogs) + seen = [module.current_mode] + for _ in range(4): + module.key_square() + seen.append(module.current_mode) + assert seen == [ + DisplayModes.NAME, + DisplayModes.INFO, + DisplayModes.LOCATE, + DisplayModes.NAME, + DisplayModes.INFO, + ] + + +@pytest.mark.unit +def test_square_cycles_on_from_a_locate_start(catalogs): + module = _object_list({"objects": "catalog", "value": "NGC"}, catalogs) + seen = [module.current_mode] + for _ in range(3): + module.key_square() + seen.append(module.current_mode) + assert seen == [ + DisplayModes.LOCATE, + DisplayModes.NAME, + DisplayModes.INFO, + DisplayModes.LOCATE, + ] + + +@pytest.mark.unit +@pytest.mark.parametrize("objects", ["catalogs.filtered", "recent", "custom"]) +def test_mixed_lists_open_in_locate_mode(objects, catalogs): + module = _object_list({"objects": objects}, catalogs) + assert module.current_mode is DisplayModes.LOCATE + + +# --------------------------------------------------------------------------- # +# NAME-mode text: real names first +# --------------------------------------------------------------------------- # + + +def _name_text(catalog_code: str, sequence: int, names: list) -> str: + module = UIObjectList.__new__(UIObjectList) + return module.create_name_text( + CompositeObject(catalog_code=catalog_code, sequence=sequence, names=names) + ) + + +@pytest.mark.unit +@pytest.mark.parametrize( + "name, group", + [ + ("Mu And", 0), + ("h 1057", 0), + ("Algol", 0), + ("CVR 117", 0), + ("HD 208526", 0), + ("STT 514", 0), + ("Winter Triangle", 0), + ("SaM 25", 1), + ("Str 12", 1), + ("TLK 69", 1), + ("WDS 4631", 1), + ("NGC 7078", 1), + ("M15", 1), + ("WDS J00568+3830", 2), + ("WDS J11246+2024", 2), + ], +) +def test_name_groups(name, group): + assert _name_group(name) == group + + +@pytest.mark.unit +def test_groups_keep_the_names_table_order(): + names = ["WDS J1", "NGC 2", "Beta", "M 1", "Alpha", "WDS J0", "Gamma"] + assert _name_text("SaM", 99, names) == ( + "Beta, Alpha, Gamma, NGC 2, M 1, WDS J1, WDS J0" + ) + + +@pytest.mark.unit +def test_name_text_sam_26(): + names = [ + "SaM 25", + "Mu And", + "h 1057", + "SaM 26", + "SaM 27", + "WDS 4631", + "WDS J00568+3830", + "CIA 50", + "HJ 1057", + ] + assert _name_text("SaM", 26, names) == ( + "Mu And, h 1057, CIA 50, HJ 1057, SaM 25, SaM 27, WDS 4631, WDS J00568+3830" + ) + + +@pytest.mark.unit +def test_name_text_wds_62246(): + names = ["WDS 62246", "WDS J11246+2024", "CVR 117"] + assert _name_text("WDS", 62246, names) == "CVR 117, WDS J11246+2024" + + +@pytest.mark.unit +def test_name_text_removes_nothing_but_the_rows_own_designation(): + names = ["Str 12", "TLK 69", "Algol", "Algol"] + assert _name_text("TLK", 69, names) == "Algol, Str 12"