AstroBucketList


Maintain astronomical imaging lists by constellation and month, with persistent imaging status, local-catalog sky charts, observing-site profiles, custom horizons and observing-plan export. User guide for version 0.46.0. [more]

Keywords: astronomy, imaging, bucket list, Stellarium, observing lists, constellation, SIMBAD, finder chart, DSS

Contents

[hide]

1 Description

[hide]

Astro Bucket List maintains Stellarium observing lists inside PixInsight 1.9.6 build 1718 or later using the V8 JavaScript runtime. It displays objects in a flat table with their IAU constellation, uses configurable planning months, and records which objects you have imaged. You create your own lists or open and import Stellarium collections.

2 Start and use the script

[hide]

Choose Script > TG Scripts > Astro Bucket List. The script requires PixInsight 1.9.6 build 1718 or later with the V8 runtime and its standard SkyChartGenerator and AnnotateImage libraries. The documentation button in the lower-right corner opens this guide.

By default, a normal launch opens an empty list. No predefined bucket list is loaded. Use Add object to enter targets, New list to create additional lists, Open to load a collection, Import list to bring one saved list into a chosen destination, or Merge lists to retain the list structure of imported files. Open offers to save any unsaved changes before replacing the current collection.

Save writes to the current collection file and asks before overwriting it. Declining keeps the existing file and your unsaved edits. The first Save asks for a filename; Save as lets you choose a separate file. Selecting an existing file in Save as or Export uses the file chooser's overwrite confirmation. When a save replaces an existing file, its exact previous contents are kept beside it as filename.sol.bak (for example, MyTargets.sol.bak). Each successful replacement updates this single backup to the immediately preceding version; no timestamped backup copies are created. Save as and Export also keep a .bak file when replacing an existing destination. Saving to a new filename creates no backup. Cancelling or declining an overwrite leaves the collection and its backup unchanged. Saving keeps the collection and backup at stable filenames, including in synchronized folders. It validates the new collection in local temporary storage, copies the exact previous bytes to .bak, then writes and verifies the new contents at the original collection path. Verified temporary replacement and recovery files are briefly created beside the collection and backup, then removed after success. A failed write keeps the collection marked as unsaved and attempts to restore the previous files. The error reports a local recovery folder containing the staged new collection and available preceding versions; retain these files if restoration fails. Completed saves remove their local temporary copies. Choose a collection location outside the entire PixInsight installation; locations inside it are rejected. Automatic reopening is off by default. Enable Remember last opened or saved collection in Configuration > General > Startup to reopen the most recently opened or saved collection on normal launches. If the remembered file is missing or unreadable, startup reports the full path and opens an empty list. Use Open to select the file at its current location; successful Open or Save updates the remembered path. The preference stays enabled, and the old path is retained until a replacement opens or saves successfully.

Select a list from the List menu, or choose All objects to see every target once. The table has one row per object and no collapsible groups. The Constellation column beside Select / object identifies the IAU region for every row, including separate Serpens Caput and Cauda entries. All sorting modes keep the same flat layout. Checkboxes in the first column select objects for Add selected to list, Move selected to list and Export selected; they do not represent imaging status. These three actions use checked objects whenever any are checked, including objects hidden by filters or in other lists. With no checks they use highlighted rows. The buttons are disabled only when neither set contains an object. Use Ctrl-click to highlight individual rows or Shift-click to highlight a range, then choose Check selected to check all highlighted objects for these batch actions. This adds to existing export checks, including hidden checked objects. Highlighting a row alone does not check it. Click the sole highlighted row again to deselect it. This clears the active object, Object information and single-object previews, while retaining export checks, filters and sorting. It does not change imaging status or collection data. When several rows are highlighted, a plain click first reduces the selection to one row; another click deselects that row. Ctrl-click and Shift-click retain their normal multiple-selection behavior. Checkbox clicks keep their separate check/uncheck action. Double-click still selects the object and switches to Finder chart. A deliberately deselected sole result remains deselected when sorting or refreshing the same view; selecting a row or navigating with the keyboard activates an object again. All filtered objects Finder charts remain available because they depend on visible rows rather than the current object. Check selected is disabled when no rows are highlighted. Check shown checks all rows in the current filtered view, retaining all previous export checks. Uncheck all clears every checked object, including those currently hidden. The footer reports highlighted rows as selected separately from checked objects. Edit object, Remove from list, object information and chart previews refer to the current row when several rows are highlighted. Object selections are temporary and are not saved in the collection or process instance. The Object type column beside the name shows the classification supplied by the object catalog, such as Galaxy, Planetary nebula or Open star cluster. Recognized catalog abbreviations are expanded for display. If only a broad classification is available it is shown as Deep-sky object or Star; an entry without a classification is shown as Unspecified. The column uses saved catalog information and does not trigger lookups.

The Comments column shows your saved imaging notes. Leftover hollow-circle symbols and generated bracketed month/constellation headings containing source-line references are removed from comments when a collection is opened or imported, and from comments saved or exported by the manager. Automatic cleanup on opening is treated as the loaded baseline and does not trigger a save prompt. It is included in the next explicit save or export. Other comment text and line breaks are retained. The cleaned comments are used throughout the table, editor, object details and exported lists. Long or multiline remarks have a compact one-line preview; hover over the cell or select the object to read the full text in its tooltip or details pane. Use Edit object > Comments to enter or change this text, then Save the collection. Existing imaging notes appear automatically.

The Filters column shows saved filter information. For an object without an explicit Filters value, recognizable filter mentions in its comments are shown, including combinations such as LRGB, SHO, HaRGB and individual emission-line filters. These are mentions from your notes, not automatically generated exposure recommendations. Edit object > Filters lets you enter any filter names, correct the suggested text or clear it. An explicitly cleared value remains blank. Filter information is saved with the collection and retained by catalog lookups.

The main window has Table, Finder chart and DSS survey image tabs. Select an object in Table to use either preview tab. The Collection group contains the file path and Open, Import list, Merge lists, Save, Save as and Export. The separate Lists group contains a compact, unlabelled list selector with New list, List details and Delete list underneath. Collection and Lists sit side by side, leaving spare space on their right. Hover over the selector to read the full selected list name. Both are inside one collapsible Collection and lists section above all three tabs. It starts expanded; click its header to hide or restore both groups together. Collapsing keeps the window dimensions unchanged and gives more room to the table or preview, retaining the active list, selection, filters, sort order, export checks and unsaved edits. The section stays in its chosen state when changing tabs. Collection, Lists, Filter objects and Sort rows remain compact and aligned to the left, with spare window width to their right. The object table and previews use the available window width. The minimum window size follows the space required by the controls, including the no-results notice and the expanded or collapsed Collection and lists and object-information sections, so shrinking the window keeps controls separated.

Above the table, a single collapsible section named Find, filter and sort contains the Find row, the Filter objects group and the Sort rows group. It starts expanded. Click its header to hide or restore all three together without shrinking the window; the table uses the freed height. Collapsing retains search text, filter choices, sorting, highlighted objects, export checks and collection edits. Filter objects and Sort rows retain separate group titles within the shared section. Find occupies its own row with a Clear search button. Clear search removes only the search text and retains filter choices, sorting and export checks. Below it, Filter objects arranges Month, Constellation, Target band, Imaging status and Object type in two labelled columns, with Selected only beside Reset filters. These controls determine which objects are shown. Reset filters clears Find and all filter options and restores every object in the selected list. It retains the selected list, sort order, highlights for currently visible rows and all export checks, including hidden checked objects. It does not change imaging status, target-band classifications or saved optical filter information. The button is disabled when no filter is active. The separate Sort rows panel changes only the order of those matching rows, using Sort by. It does not hide objects or clear filters.

Sort by sets the primary criterion. Then by optionally selects a second criterion, and Finally by optionally selects a third. Each selector offers independent direction choices; None skips that optional criterion. For example, choose Dec: increasing in Sort by, Size: largest first in Then by, and RA: increasing in Finally by. Objects run from south to north; equal declinations are ordered by decreasing size, and objects with both equal declination and equal size are ordered by increasing RA. Each later criterion applies only when the preceding selected criteria tie. Numeric coordinates use their full saved precision, without rounding or declination bands. Missing values stay last at each level, in either direction. When all chosen criteria tie, constellation name and object identifier provide a consistent final order. Reset filters retains all three sort choices.

Sort by offers Constellation, Month: January–December, Month: December–January, Size: smallest first, Size: largest first, RA: increasing, RA: decreasing, Dec: increasing, and Dec: decreasing. Month sorting follows the numeric calendar order; unassigned months stay at the end in either direction. Size sorting uses the major apparent diameter and ranks objects across all constellations in a flat table, with unknown sizes last in either direction. RA and Dec sorting also use a flat table and compare numeric J2000 coordinates, with missing coordinates last. Increasing RA runs from 0 to 24 hours; increasing Dec runs from south to north. Constellation sorting orders the rows by constellation name and then object identifier. The Constellation column remains visible in every sort mode. Sorting preserves all highlighted rows, the current object and export checkboxes and does not modify the saved collection.

Constellation choices follow the Month filter: only constellations represented by objects in the selected list and planning month are offered. All months includes every represented constellation. Previous / current / next includes the constellations of all three planning months, including the December-January boundary. Unassigned month includes only objects without an assigned planning month. The choices use the collection's constellation-month mapping, including separate Serpens Caput and Cauda entries. Other filters do not narrow the Constellation menu.

Object type choices follow the selected list and all other active filters: Find, Month, Constellation, Target band, Imaging status and Selected only. The current Object type choice is excluded when building this menu, so selecting Galaxy still leaves other matching types available to choose. Unspecified appears when matching objects have no saved classification. An empty matching set leaves only All object types.

Available selections are retained by value. A constellation or object type that becomes unavailable resets to its All option, and the table updates immediately. Month changes update Constellation first and then Object type, using the resulting constellation choice. The same rules apply when switching lists, editing object metadata or changing constellation-month assignments. If a month change removes the constellation used for an All filtered objects chart, its scope returns to Selected object. Reset filters restores all choices for the selected list. Hidden export checks and sorting are retained. Highlighting applies only to visible rows: filtering removes hidden rows from the highlighted selection while retaining highlights for matching rows. These filters do not perform catalog lookups or change saved object data.

Selected only, in Filter objects, shows the objects checked for list actions or export within the current list and other active filters. Highlighting alone does not select an object for this filter; use Check selected to check highlighted rows first. Turn Selected only off to choose more objects. Unchecking a displayed object removes its row after the click finishes; Uncheck all leaves an empty view until this filter is turned off. Reset filters turns Selected only off while retaining the checks and sorting. The option and checks are temporary view state and do not change saved collection data. Opening another collection clears them.

The Month menu offers All months, individual months, Unassigned month and Previous / current / next. The latter shows objects assigned to the previous, current or next calendar month according to your computer's local date. For example, in October it includes September, October and November; in January it includes December, January and February. These are the planning months assigned to constellations in Configuration, not calculated visibility or imaging dates. Objects with an unassigned month are excluded. The month tooltip names the three included months, and the relative choice is recalculated whenever the table refreshes. It combines with the other filters and does not change sorting, export checks or saved collection data. Reset filters returns the month menu to All months.

Find searches identifiers, names, object types, target bands, filters, catalog information, comments and constellations. The hidden trailing marker suffix used for Stellarium coordinate markers is excluded from identifier searches. The word marker remains searchable when it occurs in a displayed name, comment or other searchable text. Results update while typing. Return or Enter in Find refreshes the results without opening New list or another dialog. If exactly one object remains visible after any filter, it becomes the current target automatically, so either preview tab loads it automatically without clicking its row, provided its coordinates are valid. This does not check it for export or add it to the highlighted selection. An empty result clears the target; with multiple results, choose a row unless the current target remains visible. Month and imaging-state filters narrow the display. Double-click a target to switch to Finder chart and display it automatically. Use the Edit object button to edit its details. The object-information section can be collapsed without shrinking the window; the table uses the freed space. Expanding it keeps the window dimensions when there is sufficient room, increasing only the minimum required size if necessary. Its heading shows an identical catalog identifier and display name only once, ignoring capitalization, spacing and the coordinate-marker suffix. A distinct display name remains beside the identifier. The close button offers to save only when collection content differs from its loaded or last-saved state. Filtering, sorting, export checks, previews, local preferences, collapsing sections and applying an unchanged editor do not count as collection edits. Reverting actual content to the baseline removes the prompt; bookkeeping timestamps and automatic classification snapshots alone do not trigger it. A failed save retains unsaved changes. New objects, changed memberships, imaging data, notes and constellation-month assignments still require saving.

3 Saved view presets

[hide]

View preset, at the top of the Find, filter and sort section, recalls a named combination of Find text, Month, Constellation, Object type, Target band, Imaging status, Selected only, and all three sort choices. Set these controls, choose Save view, and enter a name. Saving an existing name, ignoring capitalization, asks before replacing it. Up to 50 presets can be stored, with names of 1 to 80 characters.

Choose a saved preset to apply it within the currently selected list. It does not switch lists or collections, change memberships, check objects, or change the Finder or DSS settings. Selected only recalls the filter flag and uses whichever objects are currently checked; it does not remember their identities. Previous / current / next remains a relative month rule, evaluated using the current local date and the collection's constellation-month mapping.

Constellation and Object type choices are restored in dependency order. If a saved choice is unavailable in the current list or filtered set, it resets to All and a message explains which filter changed. The stored preset is retained, while the selector shows Custom view. Changing filters or sorting manually also changes the selector to Custom view; choosing Custom view itself leaves the current controls unchanged.

To update a preset, use Save view with the same name and confirm replacement. The delete symbol beside Save view removes the selected preset after confirmation; the displayed filters and collection are retained. Presets are stored separately through PixInsight's per-user settings interface under AstroBucketList/viewPresets and are shared across collections on that PixInsight profile. A normal start lists the saved presets without applying one automatically. They are not included in .sol files or collection-path process instances. Saving, recalling or deleting presets does not mark the collection as modified.

4 Organize objects into lists

[hide]

A collection is the complete .sol file and owns every object independently of its lists. Each list is a named logical group inside that collection; List details changes the list name and description independently of the filename. An object may belong to no lists, one list or several lists. All objects displays every collection target once, including targets without a list membership. Repeated memberships do not create duplicate rows in this view.

Delete list deletes only the named grouping. Remove from list removes only the current object's membership in the selected list. Both keep every object in the collection, together with its catalog information, comments, filters, apparent size and imaging history. Objects whose final membership is removed remain available in All objects and can be added to another list later. A collection can be saved and reopened with no named lists.

To remove an object from the collection itself, select its row and use Delete object beside Add object and Edit object. This action always asks for confirmation, names the target and explains that it will be removed from every list together with its information. No is the default; declining or closing the question leaves the collection unchanged. Confirming removes only the current object, even when several rows are highlighted or checked. Save persists the deletion. Use Remove from list when you only want to change a grouping.

Check the objects to organize, then choose Add selected to list or Move selected to list. Checked objects take priority, including hidden checks across the collection. If nothing is checked, Ctrl-click or Shift-click to highlight rows and use those instead. The destination dialog reports the selected count.

Add selected to list retains every current membership and adds all selected objects to the destination. Move selected to list is available from named lists and All objects. Its dialog lets you choose a Source list from lists containing selected objects; the current named list is preselected when applicable. Only selected objects belonging to that source are moved. The dialog reports how many will move and how many selected objects outside the source will remain unchanged. Other memberships remain intact, and an emptied source list remains available.

In the destination dialog, choose an existing list or Create new list and enter its name. For Move, the chosen source is excluded from destinations. Add can use any list; objects already there are retained once. A new name must be nonempty and different from existing list names, ignoring capitalization and surrounding spaces. No new list is created until Add or Move succeeds. Cancel leaves the collection unchanged. Existing destination entries are retained without duplication; a move still removes their source membership.

Edit object shows List memberships as a checklist of the collection's named lists. Checked lists currently contain the object. Check or uncheck any combination, then Apply to commit the memberships together with the other edited fields. Unchecking every list keeps the object and its data in the collection. Cancel discards all proposed changes. An unchanged checklist creates no additional save prompt. If the object is removed from the currently displayed list, the manager switches to All objects and retains the edited target when it matches the active filters. Create new lists in the main window; the editor shows an explanatory row when no lists exist. Save the collection to persist membership changes.

New memberships retain the complete object information, including comments, filters, apparent dimensions, manual target band, imaging status and imaging date. Edits and imaging-state changes remain linked across memberships. Creating another membership is different from adding a duplicate catalog object: Add object still rejects a target already present in the collection and directs you to Add selected to list.

After applying, the manager displays the destination for review. Filters, all three sort choices and export checks are retained, and transferred objects that remain visible stay highlighted. Choose Save to persist the reorganized collection. Saving and reopening retains its objects, lists and shared identities; selected-object export still writes each target once, including selected targets without a list membership. Export selected beside the object actions opens the file chooser directly and writes the selected objects as one Stellarium list. It uses the same checked-first, highlighted-fallback selection rule. Cancel leaves files unchanged, and a partial export cannot overwrite the open collection file. Exporting does not change checks, memberships, imaging data or unsaved edits. The Collection Export command remains available for checked objects, one named list or Entire collection. Partial exports contain only objects in the chosen scope, including their saved metadata.

5 Save a collection path as a process instance

[hide]

The New Instance triangle in the lower-left corner saves the current collection path as a PixInsight process icon.

  1. Open a collection or create your lists and choose Save. The triangle is enabled when the collection has a filename.
  2. Save any changes you want to retain, then drag the New Instance triangle onto the PixInsight workspace.
  3. Save the process icon using PixInsight's standard process-icon or project commands if you want to keep it for another session.
  4. Run the process icon globally to reopen that collection in the manager.

The instance stores only the collection path. Objects, notes, imaging flags and unsaved changes are not embedded in the process icon; the manager reads the saved .sol file when the icon runs. The instance's path takes precedence over the most recently saved collection. You can create separate icons for different collection files.

If the file has moved, been renamed or cannot be read, the manager reports the problem instead of opening a different collection. Open the intended file and create a new instance to update the path. Save as changes the path used for newly created instances; existing process icons keep their saved paths.

6 Constellations and planning months

[hide]

Constellation names use their Unicode spelling, including Boötes, throughout the table, filters, configuration and charts. Imported constellation names may use the IAU code, the full name or the spelling Bootes.

For objects with coordinates, the constellation is calculated from the IAU boundary table of Roman (1987), after mean-equatorial precession from J2000 to B1875. This calculation works offline. For an imported object without coordinates, a recognized imported constellation is used until coordinates become available. An object without either is shown as unassigned and remains editable.

Click the Configuration gear button in the lower-right corner to open a separate settings window, then choose Constellation months to assign a planning month to each constellation. Configuration contains a Finder chart group for Sky coverage, Fit object size, Chart style, Label density and Close-up inset with its width; a DSS survey image group for Survey field and its separate Fit object size option; and a Nebula outlines group for the bundled outline brightness level and optional custom Stellarium file. Apply commits the proposed settings; Cancel discards them, including changes made in Constellation months. Chart settings and the local outline-file preference do not modify the collection. Applied constellation-month changes are collection edits. Initial assignments are provided for some constellations; others are unassigned until you choose a month. Serpens Caput and Serpens Cauda are separate planning entries. The mapping is saved with the collection and applies to every list in it.

Actual sky position determines the constellation and its planning month. An imported object whose constellation heading does not match its coordinates can appear in a different month. Imported notes remain available. These are personal planning categories; the script does not calculate local altitude, darkness, Moon distance, or visibility for a particular observing site.

7 Broadband and narrowband targets

[hide]

Target band is a separate column beside Object type. It shows Broadband, Narrowband or Unclassified. This is an imaging classification; it does not replace the catalog's object type. The cell tooltip explains the automatic evidence or identifies a manual choice. The object-information panel also shows the band and whether it is automatic or manual.

Automatic classification uses saved metadata locally, without catalog requests. Galaxies, star clusters, reflection nebulae, dark nebulae and integrated flux nebulae (IFN) always classify as Broadband in Automatic mode. Recognized galaxy types include starburst galaxies, galaxy groups, interacting galaxies and active galactic nuclei. Star clusters include open and globular clusters. SIMBAD type SBG is recognized as Starburst galaxy, both in new lookups and saved entries labelled Catalog object (SBG), without requiring another catalog lookup. Ha, OIII and SII are optional additions for these targets, so their presence does not change the band or erase the saved filter information. These exceptions use the object type; mentioning a nearby galaxy, star cluster, reflection nebula, dark nebula or IFN in the notes does not change the type of the target. For other targets, positive filter mentions in Filters, comments and catalog information take priority over object types. Ha, H-alpha, Hα, OIII, O III, SII and S II indicate narrowband; combinations such as SHO, HOO, HaRGB and LRGBHO are recognized. RGB, LRGB, explicit L/R/G/B channels and full-spectrum or broadband wording indicate broadband. For targets outside these Broadband categories, if both filter families occur anywhere in the considered metadata, narrowband wins. Explicitly negated mentions such as no OIII or without Ha are not treated as positive filter evidence.

Without recognized filter evidence, specific catalog types and descriptive metadata are used. Galaxies, reflection nebulae, star clusters, dark nebulae and integrated flux nebulae (IFN) indicate broadband. Emission nebulae, HII regions, planetary nebulae and supernova remnants (SNR) indicate narrowband. Common supported catalog abbreviations and German descriptions are recognized. Generic terms such as Nebula or Deep-sky object are insufficient and remain Unclassified. These rules are suggestions based on the available text, so review uncertain or conflicting metadata.

In Edit object, Target band offers Automatic, Broadband and Narrowband. The automatic result updates as you edit filters, comments or catalog information; hover over the adjacent result for the reason. Select Broadband or Narrowband to override the automatic result. Manual choices take priority over all automatic evidence, including these Broadband object-type rules and mixed filters, and survive Look up and Update catalogs. Choose Automatic to resume classification from the current metadata. Use the Target band filter's Unclassified choice to find entries that need a manual decision; it combines with the other view filters.

Apply keeps an edited choice in the collection; Save persists it. Save and all export scopes store the classification value and its automatic/manual mode in the object's _astroBucketList.targetBand metadata. Imports retain these fields. Automatic values are recalculated from current metadata when displayed and refreshed when saved, while manual values remain fixed until edited. Merely viewing or filtering a collection does not mark it modified.

8 Imaging state and notes

[hide]

Open Edit object and use I have imaged this object to record or clear imaging status. The Imaging status column shows the saved state and date independently of the export checkboxes. Edit object lets you enter or change the imaging date directly in YYYY-MM-DD format. The date field is always editable. Entering a date marks the object as imaged; clearing the date retains the imaged flag with an unknown date. Unchecking the imaging flag clears the date. Checking it with no date supplies today as an editable initial value. Invalid dates prevent Apply. The editor also stores an editable display name, imaging notes and Catalog information. A target recognized by its identifier or a matching primary catalog alias shares its imaging state across all lists containing it. Distinct members of a galaxy group remain separate targets.

Save persists all lists, imaging flags, dates, catalog information, comments, filter information, target-band classifications, apparent dimensions and month assignments inside the .sol file, in the namespaced _astroBucketList metadata fields. A changed window title has an asterisk, and closing offers Save, Discard or Cancel. There is no automatic overwrite of an imported source file. The script validates the new file before replacing the current one, keeps the previous primary file in the adjacent .bak file and removes temporary files after a successful save. The existing .bak is replaced only as part of a successful write. If replacement fails, it attempts to restore both the previous primary file and the previous backup; if restoration fails, the error identifies the retained recovery files. Backups with other names are left untouched. To recover an earlier version, copy the .bak file to a separate .sol filename and use Open. A single .bak retains only the immediately preceding save, not a full edit history.

9 Import and export

[hide]

Open, Save, Save as and Export share the same 32 MB limit on decoded JSON text. Before writing, the script validates the complete formatted output, including repeated object data in lists and collection storage. A larger result is rejected before changing the destination or its backup; your edits stay unsaved and the current collection path is retained. Export fewer objects or smaller lists to reduce the output. The limit is measured on decoded text, so the UTF-8 file on disk can be larger when names or comments contain non-ASCII characters.

The script accepts Stellarium observingLists JSON in .sol, .ol and .json files. A .sol file may contain one list or multiple lists. Export can write checked objects, the selected list or the complete collection. When objects are checked, Checked objects is selected initially in the export dialog. This creates a new single Stellarium list containing each checked target once, even when it belongs to several source lists. Identifiers, coordinates and saved object metadata, including imaging status and date, are retained. Objects hidden by the current filters remain part of the checked export. Save the result as a .sol file.

Full and selected-list exports preserve list UUIDs, memberships and unfamiliar Stellarium metadata fields. A checked-object or selected-list export cannot overwrite the currently open full collection. Opening another collection clears the temporary export selection.

Choose Import list in the Collection group to import objects from one saved list into a new named list or an existing destination. Select a .sol, .ol or .json file, then review the import dialog:

  1. Source list shows the lists in the selected file with their object counts. A single list is selected automatically. If the file contains multiple lists, you must choose which one to import, even if it defines a default list. Only the chosen list's objects are imported. Objects without a list is offered separately when the file contains ungrouped collection objects.
  2. Destination defaults to Create new list. New list name defaults to the selected source list's saved name and remains editable. Changing Source list updates an untouched suggested name, while retaining a name you customized. For ungrouped objects, the filename supplies the initial name.
  3. Enter a nonempty new name, or choose an existing destination from the menu. A new name must differ from existing names, ignoring capitalization and surrounding spaces. If the suggested name already exists, select that list as the destination or edit the name.
  4. Choose Import to merge the selected source objects into the collection and add their memberships to the destination. The summary reports the imported object count, new and matching collection objects, and the destination's total. Choose Save to retain the result.

Import list checks duplicates within the selected source and across the complete current collection, including objects in other lists or without a membership. Matching targets reuse one collection entry and appear once in the destination. Metadata follows the same conflict rules described below. Existing memberships remain intact. Repeating an import into the same destination adds only missing memberships and information; using a different new name creates another grouping for the same collection objects. Other source lists and source collection settings are excluded from this operation.

After Import list succeeds, Table displays the destination with view filters cleared so the imported objects can be seen. All three sort choices and checked objects are retained. The current collection path stays the same, and the source file is unchanged. Cancel, an invalid source choice, an invalid name or a file error creates no list and changes no collection data. An empty named source list can create an empty destination list.

Expand Collection and lists and choose Merge lists in the Collection group. Select one or more saved .sol, .ol or .json files. Their lists are merged into the current collection; its path and existing lists remain in place. Choose Save afterward to persist the combined collection. The source files are unchanged.

Matching objects are reconciled across the whole collection by stable object identity, catalog designation or a recognized primary catalog alias. A shared galaxy-group alias or identical coordinates alone does not merge differently named targets. Each object occurs once per list and can retain membership in several lists. Its reconciled details are shared across those memberships. Lists with a known UUID are merged; unfamiliar UUIDs add separate lists, even if the display names happen to match.

Current values take priority for conflicting coordinates, object type, display name, imaging date, apparent-size measurements and existing manual classifications. Missing values are filled from imported data. Distinct comment lines, catalog information, filter entries and catalog aliases are combined without repeating identical text. For conflicting single-value catalog facts, the current value is retained. Existing manual sizes and deliberately cleared manual catalog information remain intact. An incoming manual target-band choice is retained when there is no existing manual choice. Imaging status is combined: an incoming unmarked copy cannot erase an existing imaged flag.

The Merge lists summary reports added lists and objects, matching objects reconciled, and duplicate entries skipped. Reimporting the same data does not duplicate object memberships or accumulated text. Merge lists retains the active list, current object and export checks. All selected files are validated before committing the merge; if any file is invalid, the open collection is unchanged.

10 Load a saved collection in Stellarium

[hide]

Use the desktop version of Stellarium. The collection saved by Astro Bucket List is already an observing-list file; no conversion is needed.

  1. In Astro Bucket List, choose Save and note the .sol filename shown in the Collection group. Save includes every collection object and all named lists. To transfer only part of it, use Export and choose Selected list only or Checked objects instead.
  2. In Stellarium, press Alt+B to open Observing lists.
  3. Click the import button to open Import observing list. Browse to the saved .sol file, select it and choose Open. If necessary, choose the Stellarium Single Observing List (*.sol) file filter.
  4. Choose the imported list by name in Stellarium's observing-list dropdown. When the file contains several lists, all of them are imported and can be selected separately, even though the file filter calls .sol a single observing list.
  5. Double-click an object in the list to select it and move the sky view to its position. Named coordinate markers also work when the target's catalog identifier is absent from Stellarium's local catalog.

To transfer later changes, save the collection in Astro Bucket List and import it again. Stellarium can ask whether to replace a list with the same internal list identifier. Accept to update that Stellarium list, or decline to retain its current contents. Lists with different identifiers can coexist even when their names match. The saved collection retains its named lists. Objects without a membership are additionally exposed to Stellarium in an observing list named Objects without a list. This is an export view: reopening the collection in Astro Bucket List keeps those objects in All objects without creating a logical grouping for them. An empty collection without named lists exports an empty observing list with this name.

New objects use the entered catalog identifier as a clean Stellarium label, without an added marker suffix. Manually entered, local-catalog and SIMBAD-resolved objects use this default. Named coordinate markers are an explicit option. Date, location, landscape and other existing Stellarium fields are retained on imported entries.

Keep the collection saved by Astro Bucket List as your master. Stellarium does not manage the script's imaging flags or notes and can discard these extra fields when it edits or re-exports a list. Reimport into the saved master to retain existing imaging flags; do not rely on Stellarium to archive the extra metadata.

See the Stellarium User Guide, Observing Lists (Bookmarks) for the observing-list window, and the Stellarium observing-list reference for its file structure.

11 Remember the last collection

[hide]

Open Configuration with the bottom gear and select General and use the Startup checkbox Remember last opened or saved collection. It is off by default, including when a remembered filename already exists in PixInsight settings. With the checkbox off, normal launches start with an empty collection, and Open, Save and Save as do not record a startup filename.

Apply stores this independent preference in PixInsight settings alongside the filename. The flag uses AstroBucketList/rememberCollection and the path uses AstroBucketList/lastFile. They are local application preferences shared across collections, not collection metadata or process-instance parameters. Cancel leaves both preferences unchanged. Applying the toggle does not modify collection contents or mark the collection as changed.

Enabling it remembers the currently open file immediately; with a new unsaved collection, no path is remembered until Open or Save succeeds. While enabled, every successful Open, Save or Save as updates the path. Cancelled or failed operations retain the previously remembered path. Export, Import list and Merge lists do not replace it. Only the filename is remembered; unsaved edits are never saved automatically. The checkbox remains enabled across launches until you turn it off. Moving or renaming a file outside the script does not update its stored path. A missing or unreadable file is reported by its full path at startup; use Open to select the collection at its current location. A failed or cancelled Open leaves the remembered path intact. Adding or editing an object and then using Save keeps the same collection filename; the script does not add numbered suffixes.

Turning it off and applying clears the remembered path while leaving the current collection open. The next normal launch starts empty. A saved process instance still opens its explicit collection path, independent of this toggle. If remembering is enabled, a successfully opened process-instance collection also becomes the remembered file. The preference itself is never stored in the process icon.

12 Add an object and obtain catalog information

[hide]

Choose Add object. When All objects is active, Add to list starts with Choose a list. Select the destination before applying; the object cannot be added while this prompt is unanswered. When a named list is active, that list is preselected. No list — collection only remains an explicit choice. If no lists exist, choose No list explicitly or cancel and create a list in the main window first. Enter a designation such as M 31, NGC 7000, LDN 1228 or PN G075.5+01.7, then choose Look up. Lookup source defaults to Local catalogs, then SIMBAD. Exact names and catalog aliases are searched in PixInsight's local object-name indexes, including configured local databases, without a network request. An unambiguous match provides J2000 coordinates, available object type, magnitude, aliases and catalog provenance. Missing names, or unavailable local indexes, fall back to SIMBAD using the Harvard and Strasbourg mirrors. Choose SIMBAD — Harvard or SIMBAD — Strasbourg explicitly for richer descriptions, classifications and apparent dimensions even when a local match exists. Only the requested identifier is sent to SIMBAD; your list, notes and imaging flags are not uploaded. The source choice is retained for this manager session.

Several exact local matches open Choose local catalog object, with names, types, coordinates and source catalogs. Select the intended row and choose Use selected. Cancel leaves the form unchanged. The script never chooses an ambiguous entry or silently sends it to SIMBAD; select SIMBAD explicitly when needed. For example, an extended cluster can appear under separate catalog centers. In bulk updates, ambiguous objects are skipped and reported for review in Edit object. Local catalog aliases supplement existing duplicate detection; shared group aliases do not by themselves merge different targets.

If Find has no matching rows, the table shows a notice and the add button becomes Add searched object. It opens the same editor with your search text already in Catalog identifier. Choose Look up to retrieve information, or enter coordinates manually. Search alone never queries a catalog or adds an entry. Other active filters or the selected list may be hiding an existing object; Reset filters can widen the search. Duplicate checking covers the entire collection and known catalog aliases. When an addition matches an existing entry, choose Back to new object to retain all entered fields, or Open existing object to inspect the stored entry. Cancel leaves the collection and search unchanged. After a successful search-based addition, the manager selects the destination list, clears the view filters and highlights the new object, preserving sorting and export checks. Choose Save to persist it.

Add object rejects a target already present anywhere in the current collection, including a match through a known catalog alias. The duplicate window identifies the stored entry, its catalog identifier, the matching identifier or alias, coordinates and every list containing it. If several entries match, choose one from the selector. Open existing object closes the new-object form, switches to All objects, clears Find and all filters, selects the matching row and opens its editor. Sorting and checked objects are retained. No new object is added, and values entered in the new-object form are not copied to the existing entry. Back to new object preserves that form and the original table view. Cancel in the existing editor leaves stored metadata unchanged. Use Add selected to list for another membership. Find also searches saved catalog identifiers and aliases, ignoring spacing in identifier matches; it does not query a service for unknown aliases. Imported memberships in multiple lists remain linked; repeatedly importing the same list does not create duplicate entries.

Display name has its own Use catalog identifier button. It copies the clean catalog identifier into Display name without changing the separate Stellarium label. RA and Dec share a compact row and continue to accept decimal degrees or sexagesimal coordinates. Enter beside these fields opens a J2000 coordinate selector with separate hours, minutes and seconds for RA and sign, degrees, minutes and seconds for Dec. It prefills an existing position; missing or invalid coordinates start at zero for manual entry. At either celestial pole, Dec minutes and seconds are set to zero. A decimal-degree preview shows the resulting position. Apply copies the coordinates to the editor and updates the constellation and planning month; Cancel leaves the fields unchanged. Untouched axes retain their original catalog precision. These controls also allow an object to be added without a successful catalog lookup. Apply in the object editor and Save the collection to retain the position. The reset symbol beside Enter is Use catalog coordinates. After a lookup, it explicitly replaces RA and Dec with the retrieved position; Apply retains the change. Otherwise, edited coordinates remain intact. Coordinates still equal to their saved catalog baseline can be refreshed by SIMBAD. Existing positions without a recorded baseline are retained conservatively. Missing coordinate components are filled. The saved baseline travels with the collection, so these rules also apply after reopening it.

Choose beside Imaged on opens a date selector with Year, Month and Day controls. It starts at the entered date, or today when the field is empty or invalid. Today selects the computer's local calendar date. Month and year changes limit the day to a valid date, including leap years. Apply copies the selected date to the object editor and marks the object as imaged; Clear date removes the date while retaining the existing imaged flag. Cancel leaves the original entry unchanged. Direct YYYY-MM-DD entry remains available. Apply in the object editor commits these edits, and Save persists them with the collection.

Stellarium label is editable in Add object and Edit object. It is the exact designation saved for Stellarium's observing list and highlight labels, separate from Display name. To repair an unwanted suffix, choose Use catalog identifier, or remove marker from the label yourself, then Apply, Save and reimport the collection in Stellarium. Accept replacement of the corresponding imported list. Existing labels are retained until you edit them. Cancel discards the proposed repair.

The catalog identifier remains the target identity used for table rows, catalog lookups and duplicate checks. If the Stellarium label differs, that identity is retained as _astroBucketList.catalogIdentifier. Custom labels and catalog identity survive collection save/reopen, selected exports, list memberships and catalog refreshes. Giving two different catalog targets the same label does not merge them. Labels are not catalog aliases.

Normally leave Use coordinate marker off. Recognized catalog objects such as NGC 936 and NGC 1232 can be selected directly in Stellarium using their clean identifiers. Enabling the option for these targets adds an unnecessary visible marker suffix.

The option is useful when Stellarium cannot find a target by name, such as an obscure catalog object absent from its installed catalogs or a manually entered position without a recognized name. With the option enabled, double-clicking the imported observing-list entry creates and selects a named marker at the saved RA/Dec. Without this fallback, an unrecognized identifier may cause Stellarium to select a nearby star instead. Stellarium requires the word marker in the label to recognize this fallback and displays that word as part of the label. Use coordinate marker adds it only when explicitly enabled and is off for new objects. Use catalog identifier restores the clean label.

This option is unnecessary just to highlight a list. Stellarium's Highlight all can mark saved coordinates and display clean labels even when a name is unknown. Use the coordinate-marker option only when its double-click selection fallback is needed.

Object type is editable in both Add object and Edit object. Choose a common astronomical type from the dropdown or type your own label directly into its text field. The choices include galaxies, star clusters, emission, reflection and dark nebulae, planetary nebulae and candidates, supernova remnants, H II regions, IFN, stars and other catalog classifications. Custom types already used in the collection are also offered, so the same label can be reused for other targets. Apply updates the Object type column, its filter choices, Find and the automatic target-band calculation. Existing manual target-band choices still take priority.

Re-evaluate beside Object type proposes a classification using the saved structured catalog type, retrieved catalog summary, and the current Catalog information and Comments text in the editor. Imported descriptions are included through Catalog information. It recognizes common English and German type descriptions and known SIMBAD codes, including cached codes such as EmG, AG? and Bla. A generic Galaxy or Nebula can be refined by more specific descriptive information. Candidate wording remains uncertain; conflicting classifications or unrecognized text leave the current type unchanged. Negated claims and obvious references to nearby objects are excluded. This is a conservative text-based suggestion, not a scientific verification of arbitrary prose. Review the proposed type and the supporting text in the hint tooltip, then Apply to retain it. Cancel leaves the collection unchanged.

Re-evaluate performs no network lookup. Select a SIMBAD lookup source and choose Look up first to obtain richer catalog information. If the proposal matches the structured catalog classification, it restores that catalog type; otherwise it is saved as an editable type override that survives later catalog updates. Re-evaluation updates the automatic target-band preview, while an explicit manual target band remains in force. Use catalog type continues to restore only the structured catalog classification.

When SIMBAD is selected or used as a fallback, Look up and Update catalogs request full type descriptions. The script also includes 226 SIMBAD type definitions for interpreting saved codes and compact labels without a network connection. For example, rG and a saved Catalog object (rG) label display as Radio galaxy; NGC 5752 is therefore recognized as a broadband galaxy target. Whole generated type lines in Catalog information are made readable and deduplicated against the corresponding description. Personal prose and manually chosen Object types are retained. A previously unseen full description is displayed as supplied by SIMBAD; an unrecognized code remains visible without guessing its meaning. Candidate classifications retain their candidate status.

A manually chosen or typed object type is retained by Look up and Update catalogs and is saved in the collection as _astroBucketList.manualObjectType. The original catalog classification remains available separately. Choose Use catalog type, or clear the field, to remove the override and follow the latest catalog classification again. Apply commits the reset; Cancel leaves the stored type unchanged. Applying an unchanged editor or restoring its original type does not create an unnecessary save prompt. This classification is separate from Stellarium's selection category and the coordinate-marker option.

Catalog information is one editable field for the object description and catalog facts. Matching whole lines are shown once, including repeated object-type labels. Descriptive text imported with an object is included here. The object-information panel and Find use the same combined text. Comments remains separate for personal imaging notes. Choose Save to persist any consolidation prepared when opening a collection. List descriptions remain part of List details.

Local lookup fills missing fields and retains richer existing catalog information. A SIMBAD lookup refreshes catalog-owned types, identifiers, descriptions, available measurements and aliases; it does not erase an existing size when no new measurement is available. Retrieved positions are kept separately from manually edited coordinates. The constellation and planning month follow the retained object position. Display names, comments, filter information, imaging status and date, list memberships, manual sizes, manual target-band classifications, manual Object types and edited Catalog information are preserved, including unsaved edits in the editor and deliberately cleared fields. Catalog text is factual data, not generated prose. Use catalog text restores the latest retrieved summary; choose Apply to retain the reset. The catalog source appears in the field tooltip. Explicitly changing the catalog identifier to a different target replaces that target's catalog facts and aliases while retaining personal edits. Cancel leaves the collection unchanged.

RA accepts decimal degrees or sexagesimal hours, for example 83.822 or 05h35m17.28s. Dec accepts signed decimal degrees or sexagesimal degrees, for example -5.391 or -05d23m27.6s. Invalid coordinate ranges and impossible dates prevent Apply. Lookup uses secure HTTPS connections, response limits and timeouts, and can be stopped through the PixInsight process console.

13 Apparent object size and catalog updates

[hide]

The Apparent size column shows the major diameter and, when available, the minor diameter, in arcminutes (the prime symbol). Unknown means no measured size is available. A missing minor diameter is left unspecified. The script does not treat Stellarium's field-of-view setting as an object measurement.

Select SIMBAD in Lookup source to obtain available angular dimensions and richer metadata. Local object-name indexes do not supply apparent dimensions. Update catalogs provides the same source choices for the selected object, objects with unknown sizes, or all objects in the chosen list. In All objects, the latter scopes cover the collection; search and month filters do not narrow these scopes. Automatic mode uses SIMBAD only when the local search has no match, so choose SIMBAD explicitly when updating unknown sizes of locally known targets. Manual metadata is retained as described above. Ambiguous entries and individual lookup failures are reported without changing those objects; cancellation retains completed updates, which still require Save. No size is invented when a catalog has none. Dimensions can vary with wavelength, surface-brightness limit and source.

In Edit object, leave Use catalog size checked to follow the catalog measurement. Uncheck it to enter a major and optional minor diameter in arcminutes. For arcseconds, divide by 60; for degrees, multiply by 60. The minor diameter must not exceed the major diameter. Leave both fields empty to explicitly mark the size unknown. Manual values, including an explicit unknown, survive catalog refreshes. Recheck Use catalog size to return to the catalog value. Size metadata is saved and exported with the collection, alongside the source information.

Catalog refresh preserves imaging flags, dates, comments, filters, edited catalog information, manual dimensions and existing list memberships. Linked memberships receive the same update. A failed lookup leaves that object unchanged. Stop a batch through the PixInsight process console; successful updates remain in memory. The completion message reports failures and missing catalog sizes. Choose Save to persist the updates.

14 Plan an observing night

[hide]

Open the Observing night tab to calculate imaging opportunities for every object currently shown in Table. The selected list and all table filters apply, including Selected only when enabled. Export checks alone do not limit the plan. The planner ranks the displayed targets independently of the table's sorting. It uses the collection's saved J2000 coordinates and PixInsight's installed fundamental Sun and Moon ephemerides, without a network request.

14.1 Set the site and limits

Choose Site and limits, or open the bottom Configuration gear and select Observing. No location is assumed: enter both Latitude and Longitude in decimal degrees. North latitude and east longitude are positive; south and west are negative. Give each site a distinct name. Profile selects a saved location; New creates an unconfigured site, Duplicate copies the current profile and Delete removes it after confirmation. Up to 30 profiles retain independent coordinates, fixed UTC offsets, observing limits and custom horizons. Changing Profile retains edits within the Configuration draft. Apply saves all profile changes and selects the displayed site; Cancel discards all proposals, including creation and deletion. The Site selector in Observing night switches immediately between applied profiles, remembers the choice and recalculates the plan. Existing site settings are retained when profiles are first loaded. Height is in meters above the reference ellipsoid; zero is adequate for ordinary planning when it is unknown. Leaving both coordinates empty disables calculation until a site is configured.

UTC offset is a fixed number of hours for the chosen observing night, including any daylight saving adjustment. Examples are +1 or +2 in Central Europe and +5.5 for India. The initial offset comes from the computer's current offset, but is not automatically updated when the date changes. Check it for your site and night. All times and the noon-to-noon period use this one offset; the script does not resolve geographic time zones or change offsets during a daylight-saving transition night. Such a transition is represented in fixed-offset time rather than changing civil-clock time.

Minimum altitude defaults to 30 degrees above the geometric horizon. Darkness defaults to astronomical darkness, with the Sun center at or below −18 degrees; alternatives are −12 degrees, −6 degrees and the horizon. Moon separation is an optional minimum target-to-Moon angle from 0 to 180 degrees. Zero, the default, disables Moon filtering. A nonzero limit removes time only while the Moon center is above the geometric horizon; a below-horizon Moon never removes usable time. A custom obstruction hiding the Moon does not disable the separation limit, because it does not remove moonlight from the surrounding sky. Twilight also remains based on the geometric horizon. These limits describe geometry, not a prediction of sky brightness or image quality.

Apply saves the site and limits as local preferences and refreshes the plan. Cancel discards proposed changes. Observing preferences are independent of chart presets, the constellation-month mapping and collection data. They are shared by collections on this PixInsight profile and do not travel with SOL exports or collection-path process instances.

14.2 Configure a custom horizon

In Configuration, Observing, Custom horizon, enter azimuth and altitude pairs, one pair per line. Azimuth is clockwise from true north: north 0 degrees, east 90, south 180 and west 270. Altitude ranges from -90 to +90 degrees. A # starts a comment. Whitespace, commas and semicolons separate the numbers; use a decimal point. Enter at least two distinct azimuths, up to 720 points. The script sorts and interpolates the points, closing the profile across north. A matching 360-degree endpoint is accepted as a duplicate of 0; conflicting altitudes at one azimuth are rejected. Negative horizon altitudes are valid, but the preview clips below zero and Minimum altitude still applies.

Import reads a local Stellarium polygonal horizon point file, such as .txt or .dat. Select the file referenced by polygonal_horizon_list, not landscape.ini, a photograph or a ZIP. Import format must match polygonal_horizon_list_mode: azDeg_altDeg, azDeg_zdDeg, azRad_altRad, azRad_zdRad, azGrad_altGrad or azGrad_zdGrad. Degrees, radians and gradians are supported, with altitude or zenith distance. Rotation adds polygonal_angle_rotatez in degrees. These controls apply only to import; the editor always contains converted north-based azimuth and altitude in degrees. Defaults are degrees/altitude and zero rotation. See the Stellarium User Guide for the format.

Files are limited to 128 KiB. Invalid imports leave the draft intact. Successful import enables the horizon and displays its filename and point count. Manual edits identify it as a Manual profile. Use this site's horizon enables or disables the constraint without deleting points. Clear removes the draft horizon and disables it. Apply persists the points with the site: planning does not depend on the original file or reread later changes to it. Cancel retains the saved profile. Imports are read-only; no horizon files are downloaded or modified.

A target must clear both the directional horizon and Minimum altitude. The north/east/south/west preview helps check orientation. In the night graph the orange Horizon/min line shows the larger of the local horizon and minimum altitude along the target path; hover adds azimuth and horizon altitude. This constraint applies to the target center; allow additional room for large objects near obstacles.

14.3 Choose the night and read the results

Night of is the evening date, entered as YYYY-MM-DD or selected with Choose. Tonight uses today's date at the configured fixed UTC offset. Each plan spans local noon on that date to local noon the following day, so evening and after-midnight opportunities appear together. Times are shown in the selected site's local time using its configured fixed UTC offset. The time axis uses plain HH:mm ticks, labels the evening date at its start and the new date at midnight, and marks midnight with a vertical divider. The axis and plan information explicitly identify Local time and its UTC offset. Hover readouts and table tooltips include the calendar date. The selected night is session state; a new manager starts with today's date. A fixed 24-hour period also makes polar day and night explicit.

The information area identifies the site, date, UTC offset, darkness duration, limits and number of targets with usable time. Each target row provides:

  • Peak in dark: highest sampled altitude during the selected darkness, with its approximate time. No darkness means no peak value.
  • Above minimum: total time above the configured altitude over noon-to-noon, including daylight. With a horizon enabled this column is named Clear horizon and measures time clearing both the horizon and minimum altitude.
  • Dark time: time clearing the altitude limit and enabled horizon while the Sun meets the darkness limit, before applying Moon separation.
  • Usable: total time meeting altitude, enabled horizon, darkness and the optional Moon-separation limit. Multiple separate windows are added.
  • Best window: the longest continuous usable interval. The message below the graph lists all usable intervals; the cell tooltip also lists them.
  • Moon min: the smallest Moon separation during Dark time while the Moon is up, before applying Moon filtering. Moon down means that it stays below the horizon throughout that target's Dark time. No Dark time is shown as a dash.
  • Status: Available, Missing coordinates, No darkness, Below altitude limit, No dark altitude window, Blocked by horizon, No dark horizon window, or Moon separation limit. Targets with no opportunity remain listed.

Rank by offers Usable time, Peak in darkness and Object name. Changing this ranking does not change Table sorting. Select a row to display its altitude curve. Double-click a planning row to open that object in Finder using its normal table selection; collection objects, export checks and list memberships are retained.

The graph uses blue for the target altitude, yellow for the Moon and muted orange for the Sun. Blue background bands identify darkness; green bands identify that target's usable windows. The dashed line is the minimum altitude. Its horizontal axis spans noon to next noon and its vertical axis spans −90 to +90 degrees. Moving across the graph shows the time, target/Sun/Moon altitudes and target-to-Moon separation in the bottom message area, without a graph tooltip. Leaving restores the usable-window summary.

14.4 Export the plan

Export plan saves completed results as CSV or a printable vector-text PDF. Scope offers All results, Usable targets only and Selected rows. Select multiple planning rows with Ctrl-click or Shift-click. These selections are separate from Table checkboxes and survive changing the planning ranking. Export follows the displayed ranking. All results includes missing-coordinate and unavailable targets with their status; Usable targets only excludes them. Empty selections or unfinished plans disable export. Changed inputs invalidate old results before export can be used again.

Reports include site coordinates, height, evening date, fixed UTC offset, observing limits, horizon state, target names, peak altitude, durations and all usable windows. CSV additionally includes J2000 coordinates, horizon source, explicit local dates with UTC offsets and UTC timestamps. CSV is UTF-8 with a byte-order mark and quoted text; formula-like labels are protected for spreadsheet use. PDF uses A4 landscape pages, repeated context, page numbers and wrapped names and windows. Reports are limited to 200 pages; narrow the table filters or use CSV for larger plans. PDF headers explicitly identify local time and its offset. Peak times and windows include calendar dates, so midnight crossings remain unambiguous without a day suffix.

Choose a destination outside the PixInsight installation. The chooser asks before replacing a file; Cancel writes nothing. Export leaves collection objects, imaging status, memberships and the saved collection untouched. It is a report snapshot, not a scheduling command or collection backup. Reports intentionally contain site coordinates, so review them before sharing.

Add to list uses the same Results scope to group the chosen targets in a new or existing observing list. The default new name includes the observing date. The destination dialog checks for duplicates and retains all existing memberships and object metadata. Cancel changes nothing. Confirming changes the collection in memory; choose Save to persist the grouping. Report export itself does not change the collection.

14.5 Calculation and practical limits

The plan starts automatically when the tab is active and the site and date are valid. Date, site, limit or filtered-target changes discard obsolete results. Computation uses short timer slices, pauses when another tab or a modal dialog is active, and stops on closing. Stop cancels an unfinished calculation; Recalculate retries it. Hidden tabs defer work. Missing coordinates are reported per object; absent or unsupported ephemeris data and out-of-range dates are reported in the planning information area without a repeated popup. No catalog or ephemeris data is downloaded automatically.

The script uses the documented Position, ObserverPosition, StarPosition and EphemerisFile interfaces. All directions are apparent topocentric positions in the same equinox-based frame, including lunar parallax. Stored J2000 object coordinates are treated as fixed ICRS positions with no proper motion or radial velocity; this is intended for deep-sky planning, not moving Solar System targets or high-precision stellar astrometry. Polar-motion corrections and atmospheric refraction are omitted at this planning resolution.

Positions are sampled every two minutes; threshold crossings are linearly interpolated and times are rounded to minutes. Every traversed horizon vertex is considered between samples, so a narrow obstruction is not skipped merely because both sampled endpoints are clear. Azimuth and altitude are interpolated within each segment; near-zenith paths, peaks and very short or nearly tangent windows remain approximate. Terrain and buildings are represented only by the supplied horizon. Telescope limits, weather, extinction, Moon brightness and filter-specific background are not modeled. Review local conditions before using a proposed window. The planner does not change the collection's constellation-month assignments or claim that those planning months are calculated visibility.

Site profiles, active selection and embedded horizon points are stored together through PixInsight's settings API under AstroBucketList/observingPreferences, limited to 30 profiles and 1 MiB. Invalid settings are reported and no site is assumed; stored data is left unchanged until Configuration is applied. They are not included in collections, object metadata, process instances or chart presets, and are never sent online by the planner. The installed fundamental ephemeris and core time-scale data are read through PixInsight's documented APIs; the script neither copies nor modifies them. Sampled Sun/Moon positions, target results, the selected target curve and the chosen night remain in memory and are discarded when replaced or when the manager closes. Calculations create no runtime files. Import reads only the selected horizon file; profiles retain its basename and points, not a dependency on its original path. Explicit CSV/PDF export writes the chosen destination. CSV is prepared in memory; native PDF rendering creates a unique AstroBucketList-plan- file in the operating system temporary directory, removed after export or reported if cleanup fails. Both use the shared verified replacement writer, which may create .tgscripts-write- and .tgscripts-recovery- files beside the destination and reports retained recovery paths. Exports create no collection .bak files. The native PDF renderer launches no external program; shared Windows file protection uses the read-only volume query described below.

15 Finder charts

[hide]

Select an object with coordinates in the Table tab, then switch to Finder chart or DSS survey image. Both previews are embedded in the main window. Finder chart provides a styled sky map with stars, constellation lines and catalog objects; DSS survey image provides the survey photograph. Both use the saved J2000 position and apparent dimensions. The default Finder preferences use 45-degree coverage with Fit object size unchecked. Unknown sizes start at 45 degrees. Enable Fit object size for coverage equal to six times the major diameter, within the chart limits. DSS defaults to Fit object size enabled, using 1.5 times the major diameter when known and the configured 30-arcminute fallback otherwise. Configuration preferences apply to all targets and are remembered between launches. Changing targets never resets manual widths, fitting choices, style, label density or close-up preferences. Uncheck fitting to choose a manual DSS width, except for a target larger than its 120-arcminute limit. Catalog lookup is optional.

To chart a constellation's current table results together, first choose a Constellation in Filter objects, then open the Finder chart tab and set Chart to All filtered objects. This option uses every row currently shown, after the selected observing list and all active filters: Find, Month, Constellation, Target band, Imaging status and Object type. Checked objects and highlighted rows do not restrict this chart. All objects includes each shared object once, even when it belongs to several lists.

The chart renders automatically. Each plotted target has an accent-colored ring and a number corresponding to the Objects in table order key below the map. The key retains the table's current sort order and complete object names. Nearby targets use offset numbers and leader lines. These explicit targets are always included, independently of enabled context catalogs, catalog magnitude limits and Label density. Optional catalog objects remain background context. Modern Editorial, Vintage Atlas and Observing Atlas support this chart, as do constellation borders, star labels, nebula contours and the other Chart details. Object details also adds types and known sizes to the key.

Coverage automatically fits the visible targets and their known major diameters, including the shorter vertical map dimension. The configured Sky coverage remains the minimum width (45 degrees by default); Fit object size does not prevent fitting the complete group. This mode can expand to 170 degrees when necessary. If a group cannot fit in one projection, the information block asks you to narrow the filters rather than omit objects. The map center is a calculated field center, not a target, so no center crosshair is drawn. Close-up inset is temporarily omitted for a group; the saved single-object preference is retained.

Objects without valid coordinates remain in the numbered key with coordinates missing and are not plotted; the information block reports their count, and its tooltip lists their names. Use Edit object or Update catalogs to locate them. If no rows remain, or none has coordinates, the old preview is cleared and the information block explains what is needed. Filter, list, sort and relevant object changes update the chart automatically when Finder is active, or the next time its tab is opened. Removing the Constellation filter, including with Reset filters, returns Chart to Selected object. The chart scope is a temporary view choice, not collection data or a saved preference. DSS survey image continues to show the individually selected object.

Use the bottom Open as image symbol to open the complete constellation chart and its object key in a native PixInsight image window for saving or printing through your normal image workflow. The chart is 1440 pixels wide; its height grows to include the full key. Zoom affects only the on-screen preview, not this output. Export Finder chart also includes the complete object key in SVG or PDF.

Both previews support mouse-wheel zoom. Rotate the wheel forward to zoom in around the pointer and backward to zoom out. Drag with the left mouse button to pan; double-click with the left button to fit the whole chart or image. The view is bounded from Fit to 1600 percent of the fitted size, with the current level shown in the information block. Finder redraws the cached vector drawing at the display resolution, keeping its lines, labels and symbols sharp. DSS magnifies its loaded survey pixels without adding resolution. Zoom does not change sky coverage, retrieve a new DSS field or query a catalog. Open as image opens the complete raster image; SVG/PDF export retains the full vector chart. Each tab retains its own zoom and position while switching tabs, and resizing retains the viewed region where the edges allow. Changing targets or preview settings resets the corresponding preview to Fit. Zoom and pan do not modify collection data or saved configuration.

Finder charts are interactive. Hover over the center of a star, deep-sky symbol, target crosshair or numbered table marker to see its identifier or name, object type, apparent size and catalog magnitude when available. The hover line is below the chart; its tooltip includes J2000 coordinates and the catalog source. Catalog magnitude passbands differ. Unknown sizes and magnitudes remain explicitly unavailable. Nebula outlines without a corresponding catalog symbol are context only. The independent close-up inset supports the same interaction.

A short interaction hint appears below the Finder chart; the chart itself has no tooltip. Hovering over a symbol replaces the hint with its catalog facts. Click a symbol to select it. A colored ring identifies the selection, and the Selected line below the chart retains its information while the pointer moves elsewhere. Click empty sky to clear it. Selecting an object does not change the chart center, the table selection, export checks or collection data. Zoom and pan continue to work; dragging does not select objects, and double-click still fits the complete chart.

For a matching collection object, Edit object opens its normal editor directly, including when it is hidden by the current filters. Show in table switches to All objects, clears table filters and reveals the entry without opening its editor; sorting and export checks are retained. Matches use saved object identities and catalog identifiers or aliases, rather than coordinate proximity alone. Ambiguous matches require choosing an entry. Editing preserves existing manual metadata unless you explicitly change it.

For an object absent from the collection, Add object opens the normal editor with the available local chart coordinates, type, apparent dimensions and catalog information. Review the values and list destination, then Apply. Cancel changes nothing. The active named list is preselected; from All objects, choose a list or explicitly choose No list. Duplicate checking runs again on Apply. No marker suffix or imaging status is added. Use Look up in the editor if you want additional catalog information; the normal local/SIMBAD lookup rules apply.

Local Gaia XPSD stars do not carry source identifiers. They can still be inspected by position and magnitude, with a Star at coordinate caption. Adding one leaves Catalog identifier empty for you to enter a known identifier or your own unique label; the positional caption is not presented as a Gaia source ID. Hover and click never make network requests. Catalog facts describe the rendered chart; the explicit collection target retains its saved type and size. Selection and hover rings are preview aids and are excluded from Open as image and SVG/PDF exports.

For DSS survey image, choose a square Survey field of 5 to 120 arcminutes in Configuration. Fit object size is beside Survey field in Configuration's DSS survey image group. The survey loads automatically when its tab is selected and after its field or fitting setting changes. If the object's major diameter exceeds 120 arcminutes, the request always uses 120 arcminutes, even when Fit object size is unchecked. The explanation appears in Configuration and in the consolidated information block above the preview. Configuration continues to show the preferred width; the temporary maximum does not replace it. Returning to a smaller target uses the preferred width or its size-based fit. The STScI survey image is centered on the object and displayed with a crosshair. This method requires internet access and is useful for identifying the appearance of a target and its immediate surroundings.

The bottom Export Finder chart symbol (document/save icon) is enabled only when the Finder tab has a loaded chart. Choose a filename ending in .svg or .pdf in its file dialog. Export saves the entire displayed drawing, including an enabled close-up inset or the full filtered-object key; the current zoom and pan do not crop it. The existing information block reports the saved filename, with its full path in the tooltip. The file chooser asks before replacing an existing document. Cancel retains the chart and existing files. Export does not save or modify the collection.

SVG and PDF contain vector lines, symbols and labels, so they remain sharp when enlarged. SVG labels are converted to paths to preserve their fonts and Greek characters in other applications. PDF uses the same drawing on one page. Documents are 297 mm wide; their height follows the chart proportions, including an inset or a long key. Use the viewer's Fit to page option when printing on a different paper size. For a very long object key, narrower filters produce a more readable printed page. Open as image remains available for the raster image workflow; DSS does not offer SVG/PDF chart export.

For the Finder chart, choose Sky coverage from 0.1 to 120 degrees in Configuration. The chart renders automatically for the current target and settings, using the vector chart engine supplied with PixInsight. A separate title band sits above the map; coordinate labels sit outside its frame. The lower band provides J2000 coordinates, an angular scale measured at the field center, and a legend for the object types drawn. Different catalog types use distinct astronomical symbols. Stars have magnitude-scaled sizes and separating halos, and label placement avoids their symbols. The overview image is 1440 pixels wide; its height adapts to the legend and any table-object key. The width setting describes the horizontal field; the vertical field is smaller. An accent-colored center crosshair identifies the selected target. The header shows the target name, apparent size, field width and orientation. North is up and east is left. The sky map does not draw an image or camera FOV rectangle.

The bottom gear opens one Configuration window with Finder chart, DSS survey image, General and Observing tabs. Finder chart combines Chart preset, appearance and coverage, Annotations, Catalogs and Nebula outlines. Sky coverage, Fit object size, Close-up inset and Projection are on the left of the appearance group, with compact Chart style and Label density choices below. The right column contains Milky Way shading and its strength, Star density, Star size and Use catalog star colors. The horizontal detail editor shows annotations, the catalog checklist and its properties together. DSS survey image contains Survey field and its own Fit object size checkbox. General contains Remember last opened or saved collection and Constellation months. Observing contains the site, UTC offset and night limits. The window opens on Observing or DSS settings when that main tab is active, otherwise on Finder settings.

All Configuration changes remain proposed until Apply; Cancel discards them, including new, replaced or deleted chart presets. Apply remembers current chart settings for all targets and future launches, and refreshes only affected previews. An unchanged Apply reuses the loaded image. Previews pause while Configuration is open. The main Finder tab contains chart navigation, the chart scope choice, information and the interactive preview; its bottom object actions remain available for editing, adding or revealing the selected symbol. The main DSS tab contains its consolidated information block and survey image.

Chart style offers Modern Editorial, Vintage Atlas and Observing Atlas. Modern Editorial is the default, with a dark sky, sans-serif labels, blue-gray catalog markings and a cool accent crosshair. Vintage Atlas uses warm ivory paper, sepia stars and catalog markings, serif labels, italic constellation names, fine double rules and a rust-colored target crosshair. Observing Atlas uses white paper, black stars with separating halos, restrained constellation colors and colored symbols that distinguish galaxies, clusters and nebula types. All three styles use the same projection, coordinates, field width, catalog objects and label-density rules. The selected style applies to the preview, Open as image and vector exports.

Applying a changed Chart style in Configuration updates only the Finder preview automatically. It retains sky coverage, Fit object size and catalog-detail choices. The choice remains active as you select other targets and is remembered locally for future launches. It does not modify the collection or DSS survey image. Each style has its own session cache entry.

Projection in Configuration defaults to Automatic. Fields up to and including 20 degrees use Gnomonic, which keeps great circles straight and works well for close-ups. Wider fields use Stereographic, which preserves local angles and avoids the severe edge stretching of wide Gnomonic maps. Both retain north up, east left, J2000 coordinates and the requested horizontal angular width. Automatic chooses independently for an enabled close-up, so a broad Stereographic overview can accompany a Gnomonic inset. Select Gnomonic or Stereographic to use that projection for both maps. The overview header and information block identify the effective projection. The scale bar measures angular distance at the field center; scale elsewhere varies with projection.

All filtered objects fits the target positions and known major diameters using the selected projection, with margins on both map axes. Automatic can switch to Stereographic as the group expands. Very large groups or extended targets can exceed the 170-degree group limit or fail to fit in the map's shorter vertical dimension; narrow the filters or try a different projection. Targets are never silently dropped to make the group fit.

Milky Way shading in Configuration is enabled by default. It draws the integrated-starlight brightness contours supplied by PixInsight's local MilkyWay database, derived from Gaia DR3. The contours form a subtle background with colors adapted to each chart style; they are independent of nebula outlines and object markers. Shading strength ranges from 5 to 30 percent and defaults to 10 percent per brightness level. Overlapping levels accumulate opacity. These schematic contours show the broad structure of the Milky Way, not a photographic survey or a prediction of local sky brightness. Configuration reports whether the database is available. If it is missing, shading controls are disabled, the chart reports its omission, and the saved preference is retained. No database is downloaded, copied or reconfigured.

Star density offers Sparse, Normal and Dense independently of Label density and deep-sky catalog limits. Normal adapts the stellar magnitude limit to the field width. Sparse sets the limit one magnitude brighter; Dense makes it one magnitude fainter, up to magnitude 15. The actual count depends on available local catalog coverage. Without a configured local Gaia catalog, only the bundled bright and named stars are available; selecting Dense cannot supply absent stars. The close-up uses its own coverage to set the limit.

Star size scales magnitude-dependent symbols and their halos from 50 to 200 percent, with 100 percent as the default. It changes neither star counts nor sky coverage or deep-sky object sizes. Use catalog star colors is off by default, preserving black stars in Observing Atlas and the neutral ink of the other styles. When enabled, the native engine derives schematic colors from available catalog color indices; stars without color data retain the style's neutral color. These are not calibrated photographic colors.

Projection, Milky Way shading and strength, and star appearance apply to all targets, including filtered-object charts, raster images and SVG/PDF exports. They are stored in PixInsight's per-user settings database. Apply refreshes only the affected preview; Cancel retains the current settings and image. Changing these options does not edit the collection, overwrite object metadata or alter DSS settings.

Constellation borders in Chart details is enabled by default. It draws dashed region boundaries from PixInsight's bundled constellation-border data, using colors suited to the selected style. Solid lines connect the constellation stars; a dashed sample in the footer identifies the borders. The boundaries use the same sky projection as the chart and work across the zero-hour RA seam and near the celestial poles. Turn the checkbox off for a simpler map. The active preview updates automatically. Changing this option retains the field width, object selection and DSS preview. Each border setting has its own cached chart. Applying Configuration remembers the option while selecting targets and across launches; borders are enabled by default. Borders do not require internet access or change object counts.

Both preview tabs load automatically when selected. Changes to the current target or the active tab's settings are combined over a short delay, then use the latest values. Hidden tabs do not render or download; their updates wait until selected. Returning to an unchanged loaded preview reuses its bitmap without another request. Rendering is deferred while the manager is busy or a child dialog is active. Leaving a tab or closing the manager stops its pending timer. Finder uses local catalogs; new DSS fields require an internet connection. Loading can take a few seconds, particularly for a large survey image or detailed chart. Failed requests are reported in the information block without a popup or repeated automatic retry; choose Retry, change settings, or return to the tab to try again.

Each tab has one information block immediately above its preview, combining the target, J2000 coordinates, apparent size, loading/result status and any coverage limitation or error. The Finder block also reports whether outline data is available. A duplicate identifier and display name is shown once. The blank image area contains no additional instructions. The bottom Open as image symbol button becomes available when a preview tab is active and its image has loaded. It is disabled on Table and while the active preview has no loaded image.

The Finder chart tab in Configuration groups the Catalogs checklist and its properties separately from the Annotations controls. Annotations contains Constellation borders, Nebula contours, Star names, Star magnitudes and Object details. The checkable All details symbol in the bottom bar selects or deselects all available annotation switches and catalog layers, including Messier, plus Milky Way shading. It is enabled only on the Finder chart tab. Its pressed state means all available details are selected; its tooltip describes whether clicking will enable or disable them. It skips missing catalogs and unavailable outline sources. It retains per-catalog label and magnitude properties, projection, shading strength, star appearance and the other Chart settings. All details updates the same persistent annotation, catalog and shading preferences as Configuration. Changing individual details updates the symbol's pressed state. Constellation borders, Messier and the installed NGC/IC catalog start enabled. Nebula contours starts enabled when bundled databases or a valid custom file are available; the other catalogs and annotations start disabled. Making an unavailable outline source available also enables contours. You can switch any of these defaults off in Configuration; applying changes remembers the choices across targets and launches.

In Catalogs, check a row to include that catalog; select its name to edit the properties to the right of the checklist. The Contains column explains its purpose. All listed catalogs are local files supplied by PixInsight; missing files or classes are marked Unavailable and cannot be checked. The choices are:

  • Messier: bright deep-sky objects, including galaxies, nebulae and clusters.
  • NGC/IC: a larger general catalog of galaxies, nebulae and clusters.
  • Caldwell: a curated selection of additional deep-sky objects, overlapping other catalogs.
  • Collinder: open star clusters.
  • Green SNR: Galactic supernova remnants.
  • WISE H II: Galactic H II regions and candidates. Its sizes describe infrared apertures, which need not match the extent seen in an optical exposure.
  • Mandel–Wilson: large, diffuse integrated flux nebulae.

The installed data determine which choices are available. Hover over a catalog for its description and local file path; hover over the property summary for available data fields. The Finder checklist exposes the listed catalog selections. PixInsight also supplies additional catalogs through ExtendedSources; these are available to local object lookup and the native outline libraries, while the Finder checklist remains limited to the selections described here. The star background independently prefers configured local Gaia data, falling back to bundled bright stars. Constellation geometry and nebula contours are separate layers. No online catalog is queried for Finder rendering.

Labels toggles text for the selected catalog while retaining its markers. Magnitude offers Automatic, Custom and No limit when the catalog supplies magnitudes. Automatic adapts to field width (up to magnitude 14 for Messier and NGC/IC, and 16 for Caldwell and Collinder); the summary shows the current threshold. Custom lets you enter the faintest magnitude from -5 to 25; larger values include fainter objects. No limit disables magnitude filtering. Unknown magnitudes are retained. Magnitude controls are disabled for Green SNR, WISE H II and Mandel–Wilson, which do not supply magnitudes. Catalog magnitude passbands can differ and are not interchangeable. These are drawing filters, not edits to the catalog data. Applying Configuration remembers these properties while choosing targets and after restarting. Save a Chart preset to retain additional named combinations. Catalog properties are not written to the collection or to PixInsight's catalog files. Automatic limits are recalculated for a close-up's own coverage; custom limits apply equally to overview and close-up.

Star density adapts independently to the field width. Markers remain visible for every included object after duplicate removal; labels use a spaced subset, preferring brighter targets, with overlap optimization. Label density and per-catalog Labels can reduce clutter without hiding markers. Dense catalogs, especially WISE H II, can make wide Galactic fields busy. The information block reports catalog objects after duplicate removal, excluding stars, so the number can exceed the text labels. Each combination of catalog selection and properties has its own session cache entry. Changes affect only the Finder preview, retaining collection data, imaging flags and DSS preview.

Star names prefers common names from the bundled named-star catalog and otherwise uses the catalog designation. Star magnitudes adds catalog brightness values, including unnamed stars when a local Gaia database provides them. The passband depends on the source catalog; Gaia and named-star magnitudes are not necessarily directly comparable. Label density offers Sparse, Normal and Detailed. It adjusts the number and spacing of star and object labels without changing the stars or object markers drawn. Brighter objects are preferred, with collision optimization; crowded fields do not show every label.

Object details adds short lines for catalog object type, angular size in arcminutes and magnitude, omitting unavailable values. Major and minor sizes are shown when the catalog supplies an axis ratio. Messier entries can obtain object types from their linked local NGC/IC records. Very large outlines retain compact name labels; the close-up information band provides the selected target's type and saved apparent size.

Nebula contours draws actual catalog polylines, separately from circular or elliptical object markers. By default it uses the local OpenNGC-Outlines and Nebula-Outlines databases supplied with PixInsight through ExtendedSources. No separate file or internet connection is required. Configuration shows Bundled PixInsight nebula outlines available and offers All levels, Faintest extent, Standard (the default), and Brightest parts. When a chosen level is absent for an object, PixInsight uses the nearest available level. The databases are queried for the chart field, including a separate query for a close-up; only represented objects have outlines, so a field may contain none.

Choose file optionally selects a local Stellarium/SkyChart outlines.dat file with J2000 coordinates. The file is validated before use and remains an explicit override until Use bundled is applied. Configuration reports the loaded filename and contour count, or a missing/invalid file. Its tooltip gives the full path or error and identifies the Stellarium format. Brightness-level selection is disabled for a custom file. Use bundled deselects the file without deleting it and restores the native databases. Apply saves the source and brightness level locally and updates Finder; Cancel discards proposed changes. A deliberately disabled Nebula contours option remains off when switching between available sources. If no selected source is available, the checkbox is disabled. The information block identifies the source and reports how many contours intersect the overview. Source and brightness settings do not modify collection data or DSS, and persist across launches. Edited custom-file contents invalidate cached charts. The script does not copy, modify or download PixInsight catalog databases.

Close-up inset in Configuration's Finder chart group adds a separately projected square map beside the overview, keeping the whole overview visible. Its preferred Coverage is in degrees, defaults to 2 degrees and applies to all targets. If this width is at least as large as an object's overview, that chart uses half the overview width, with a minimum of 0.1 degrees, while the preference remains unchanged. At the minimum 0.1-degree overview the inset is temporarily hidden. A wider overview restores it automatically when the saved inset preference is enabled. The close-up uses the same style, catalogs and detail choices, with star density adapted to its narrower field. Both maps mark the same target center. With the inset enabled, the chart is 2080 pixels wide, with a 1440-pixel overview and a separate 600 by 600 pixel close-up panel. Its height adapts to the symbol legend. Open as image and SVG/PDF export include the complete chart with all selected details.

The Configuration window displays the preferred preview widths. Sky coverage affects Finder chart; Survey field affects DSS survey image. You can configure both previews even without selecting a target. When Fit object size is checked, its width control is read-only and shows the fallback width used for unknown sizes. Uncheck fitting to edit that width. A known size produces a fitted field for each target without replacing the stored width; an unknown size does not turn fitting off for later targets. The DSS maximum and close-up bounds likewise constrain only the displayed chart. Apply saves these preferences locally and updates the active affected preview; a hidden preview updates when selected. Cancel retains both active and saved preferences. These settings are independent of collection data and process-instance paths. Constellation months remain collection data, and the outline source and brightness level remain local preferences.

Each preview tab keeps its own coverage setting and loaded image. Switching tabs retains both previews. Selecting a different object, changing its position or size, or editing preview settings clears the affected preview so a stale image is not shown for a new target. Selecting the relevant tab automatically updates a missing or stale preview using its current settings. A target without coordinates cannot start a preview request. The chart source appears in the same information block as the other preview messages. Configured full Gaia DR3, EDR3 or DR2 XPSD catalogs are preferred through the Gaia process's BestAvailable selection. If those are unavailable, a configured Gaia DR3/SP database is used. The bundled named-star catalog supplements the bright stars missing from Gaia. If no usable Gaia database is configured, the bundled named and bright stars provide an offline chart with fewer faint stars. Star positions are propagated to J2000 for consistency with the list coordinates. Constellation, Messier and NGC/IC annotations also use files bundled with PixInsight. Sky charts do not require a network connection and do not change the Gaia configuration.

The bottom Open as image symbol button beside the gear loads an independent native PixInsight image from the active preview; it does not open another preview dialog. Close the list manager to work with that image and save it using PixInsight's usual image commands. The exported image includes the target, coordinates, orientation and sky coverage. Preview charts are cached for the current manager session; temporary files are removed when the manager closes. An image already opened in PixInsight retains its loaded pixels.

A preview error appears in the information block without changing the collection or existing image windows. DSS limits its width to 120 arcminutes; the DSS tab enforces this width for objects exceeding the limit, regardless of automatic fitting. Use Finder chart for a larger field. Automatic sky coverage is capped at 120 degrees; the Finder chart tab indicates when this limit is reached. Survey images describe the historical survey exposure; sky charts plot catalog positions and symbols. Neither mode calculates current visibility, guiding coordinates, altitude, or exposure conditions.

15.1 Chart navigation

Select a symbol in the Finder chart and choose Center on selection above the preview, beside Back, Forward and the home symbol. The chart is projected again around that object's J2000 position, using the current Finder preferences and details. It starts at Fit. Coverage follows the configured preferred width or Fit object size rule for the new target. This action does not add the object to the collection, alter its metadata, select its table row or change the DSS target. Table filters, sorting, list choice and export checks are retained. A numbered target in an All filtered objects chart can be explored in the same way.

Back and Forward arrow buttons above the chart move through the session's visited targets. Back can return to the original single-target or filtered-group chart. Current chart settings are retained; history does not revert a later style, coverage, catalog or preset change. Zoom and pan are restored when the saved viewport's settings still match the current settings; otherwise the chart starts at Fit. Centering a new object after going back replaces the forward branch. History is limited to 32 target snapshots and does not retain separate native image windows.

While browsing, Chart selection replaces the Chart source selector, and the information block states that the table and DSS target are unchanged. The home symbol returns to the current table target or filtered-object chart and clears browsing history. Changing the table target or the contents/order of a filtered-group chart starts a new browsing context. Double-clicking a table row explicitly returns Finder to that row, even if it was already the selected table target. Opening another collection clears history. Switching tabs, or refreshing the same table input, retains the browsed target.

The close-up inset remains interactive. Unnamed local Gaia stars retain their coordinate captions and empty source identifiers after centering. Hover and selection alone never recenter the chart. If rendering a new center fails, the error replaces the preview and Back remains available. Navigation uses local chart catalogs and does not trigger SIMBAD or DSS requests. Open as image and SVG/PDF export use the complete currently centered chart.

15.2 Chart presets

Open Configuration with the bottom gear and select its Finder chart tab. The settings below Chart preset are the current Finder configuration: appearance, coverage, annotations, catalogs and nebula outlines. A preset is a named copy of these same settings, useful for recalling different chart arrangements. It is independent of View preset in the table. Adjust the controls, choose Save preset, and enter a name. The proposed preset captures the values shown in Configuration, including edits that have not yet been applied. A preset stores preferred sky coverage and Fit object size, style, projection, label density, close-up settings, Milky Way shading and strength, star density, size and colors, constellation borders, annotations, enabled catalogs, each catalog's label and magnitude options, and the outline source and brightness level.

Presets store preferred values, not the fitted width or temporary inset limits of the current target. They exclude targets, table filters, list selection, export checks, zoom, pan, navigation history, DSS settings, observing preferences, startup settings and constellation-month assignments. Choosing a preset fills the controls in Configuration without changing the displayed chart. Apply commits the proposed settings for every target, including the current browsed chart object. This preserves navigation history and redraws automatically when Finder is active. Applying the same combination does not require another drawing.

Save preset with an existing name asks before replacement; names are compared without regard to capitalization. The delete symbol beside Save preset proposes removal of the selected preset after confirmation, retaining the settings shown below. Up to 50 chart presets are supported, with names of 1 to 80 characters. Manual changes to Finder settings switch the selector to Custom settings. Choosing Custom settings itself retains the values and only detaches the preset name. Save preset, replacement and deletion remain proposals until Apply in Configuration. Cancel in Configuration discards all proposed changes, including preset-library changes. Cancel in the naming window creates no preset. DSS, General and Observing settings are not part of a chart preset.

If a preset requests a local catalog or bundled outlines that are unavailable, those details are omitted and a message explains what was skipped. The saved preset is retained, while the proposed combination is shown as Custom settings. A missing or invalid custom Stellarium outline file rejects the preset before changing the current settings; there is no silent substitution of another file. Choose an available source in Configuration and save the preset again. Custom presets retain the file path, not a copy of the outline data.

Named chart presets use the AstroBucketList/chartPresets key in PixInsight's per-user settings database and are shared across collections on that profile. Startup restores the menu without automatically applying a named preset. Apply remembers the current Finder configuration, including annotations and per-catalog properties, under AstroBucketList/previewPreferences. These choices are restored on the next launch without selecting a preset again. Named presets retain additional reusable combinations separately. Presets are not included in .sol files or collection-path process instances. Saving, applying or deleting one does not mark the collection as modified.

16 Data sources

[hide]

The program code and original documentation are MIT-licensed. SIMBAD-derived object-type tables are separately licensed under the Open Data Commons Open Database License (ODbL) v1.0; the MIT license does not relicense them. The installation includes AstroBucketList-DataNotices.txt, the complete license in AstroBucketList-ODbL-1.0.txt, and the machine-readable AstroBucketList-SIMBAD-otypes.json beside the script in src/scripts/TGScripts. That JSON copy contains the 226 extracted definitions and the script's presentation labels for redistribution; it is not a runtime dependency. Preserve the attribution and ODbL license or URI when redistributing these data, and follow its share-alike and access conditions for publicly used derivative databases. Other data sources retain their respective terms.

SIMBAD is operated at CDS, Strasbourg, France. Citation: Wenger, M., et al. (2000), The SIMBAD astronomical database. The CDS reference database for astronomical objects, Astronomy and Astrophysics Supplement Series, 143, 9–22, doi:10.1051/aas:2000332.

Constellation boundaries are from Roman (1987), CDS catalog VI/42, distributed in Astropy's constellation data. Local object-name searches use PixInsight's installed ObjectNameIndex library and its catalog indexes. Nebula outlines use the installed AstronomicalCatalogs library and ExtendedSources process. These PixInsight components are developed by Pleiades Astrophoto S.L. and remain in the installation under their existing licenses. Online object data are supplied by the SIMBAD astronomical database at CDS, Strasbourg; survey finder images are supplied by the Digitized Sky Survey at STScI. The bundled object-type definitions are a snapshot of SIMBAD's otypedef table retrieved on 2026-11-14 through the SIMBAD TAP mirror at Harvard. Reading saved classifications does not download that table at runtime.

Sky-chart rendering uses the SkyChartGenerator and AnnotateImage components supplied with PixInsight, developed by Pleiades Astrophoto S.L., together with their annotation catalogs and configured local Gaia data. Milky Way shading reads the installed MilkyWay extended-source database of Gaia DR3 integrated-starlight contours through the supplied native layer; the database is not redistributed by this script. The chart recording, symbols, label placement and vector drawing interfaces remain part of the user's PixInsight installation under their existing licenses, including the PixInsight Class Library License. This product is based on software from the PixInsight project, developed by Pleiades Astrophoto and its contributors (https://pixinsight.com/). The WISE catalog is described at WISE Catalog of Galactic HII Regions. The script adds its target markings, appearance settings, object key and manager controls around the installed engine.

17 Network connections and storage

[hide]

Collection, preview and observing-plan writes reject locations inside the PixInsight installation. On Windows, choose direct local drive paths; network shares, substituted drive letters, symbolic links, junctions, and ambiguous device names are refused. Ordinary cloud placeholders are supported. On Linux and macOS, resolved links and directory identities are checked against the installation.

On Windows, file protection runs the operating system utility mountvol.exe from the Windows System32 directory, using the read-only /L option to identify volumes and reject alternate drive mappings. It does not change mounts, request administrator privileges, process images, or use a command shell.

Replacing a text or data file briefly creates verified .tgscripts-write- and .tgscripts-recovery- files with unique names beside that file. The outside directory entry is replaced without writing through a pre-existing hard link. Successful operations remove these temporary files. If restoration fails, the error identifies the retained recovery file; keep it until the previous contents have been recovered.

Observing-window planning, horizon import, CSV/PDF plan export, local catalog lookup, Finder rendering and navigation, chart presets, vector zoom, SVG/PDF export and bundled outline or Milky Way searches make no network connections. The planner keeps observing-site coordinates local. An explicit SIMBAD source choice, a missing local match, or unavailable local indexes triggers the SIMBAD lookup. Ambiguous local matches require a choice and do not trigger a fallback. SIMBAD lookups use HTTPS connections to simbad.cfa.harvard.edu and simbad.cds.unistra.fr and send the requested object identifier. DSS previews use an HTTPS connection to archive.stsci.edu and send the target coordinates and requested field dimensions. These requests identify PixInsight through CoreApplication.agentName followed by AstroBucketList/0.46.0.

Downloads require TLS with certificate-chain and hostname verification. Failed transfers, non-200 HTTP responses, unexpected content types and empty responses are rejected. SIMBAD responses are limited to 2 MiB and checked for the expected text format, a complete single-object record and valid coordinate components before updating an object. DSS GIF responses are limited to 128 MiB, checked for complete framing and bounded dimensions, then decoded with PixInsight before being accepted into the session cache. A SHA-256 digest held in memory checks the temporary DSS file after writing and before its subsequent cache reuse; missing or altered files are downloaded again. Rejected preview files are removed when possible, otherwise their paths are reported and retained for cleanup on closing.

These live services do not provide a publisher-supplied cryptographic digest or signature for the requested responses. TLS protects the transfer; the response checks detect malformed or incomplete data, and the local digest detects changes after download. A locally computed digest does not independently authenticate the publisher's payload. Whether these mechanisms satisfy CPD rules 4.6 and 6.3 for live responses remains subject to PTeam clarification.

Save validation and recovery files use uniquely named AstroBucketList-save directories under the operating system temporary directory. Preview GIF and PNG files use uniquely named AstroBucketList filenames there. Successful saves remove their temporary copies. A failed save can retain recovery files at the path reported in its error message. Closing the manager removes its preview files. Vector recordings and the bounded preview-tile cache remain in memory. PDF export temporarily creates an AstroBucketList-export file in the operating system temporary directory and removes it after export; a cleanup failure is reported with its path. SVG is generated in memory. SVG/PDF destinations use the selected file-dialog path. Verified .tgscripts-write temporary files and, when replacing a document, .tgscripts-recovery files are created beside that destination and removed after success. A failed replacement attempts to restore the prior document and reports any retained recovery path. These chart exports do not create collection .bak files. Collection files and their .bak backups use the destinations chosen in the file dialogs. The native Milky Way layer caches its local contour data in memory. Saved view presets use the AstroBucketList/viewPresets key in PixInsight's per-user settings database; they contain only preset names, search text, filter values and sort choices. Named chart presets use AstroBucketList/chartPresets in the same per-user settings database; they contain preset names, Finder preferences, catalog and annotation choices, and the configured custom outline path and brightness level. They store no object data or navigation history. The chart interaction index, selections and the history of up to 32 target snapshots remain in memory and are discarded with the chart context or session. Current preview preferences, including Finder appearance, annotations, catalog properties and DSS framing, use AstroBucketList/previewPreferences in PixInsight's per-user settings database. The custom outline path and bundled outline brightness level use AstroBucketList/contourPath and AstroBucketList/outlineLevel in the same store. Local catalogs are read through PixInsight's libraries and processes from installed or user-configured locations; their configuration is not changed.