[3.3] Framing Assistant: Add multi-source cache support

[naixx]

Framing Assistant: Add multi-source cache support for SKYATLAS. New caches should be placed inside framingAssistantCachePath as subdirectores. Selecting cache UI is added to skyatlas mode of Framing Assistant

🚀 Purpose

Since we have new excellent sky survey by sigm.de that would be great to have ability to use Framing Assistant in different surveys. A user can add existing caches as subdirectories of framingAssistantCachePath and switch them in runtime when sky atlas is selected. Clearing cache clears all caches including subdirectories. If no subdirectores were found, no combobox is shown (same as previous ui behavior)

🧪 How Was It Tested?

Manual tests. Adding, removing subdirs, empty subdirs, invalid cacheinfo in subdirs

✅ PR Checklist

• [ x] All unit tests pass
• [ x] UI changes tested across Light, Dark, and Night themes (if applicable)
• [ x] Plugin API compatibility reviewed
  • [x ] No breaking changes to interfaces
  • [x ] No changes to method/class signatures (especially optional parameters)
• Changelog.md updated (if applicable)
• Documentation updated (if applicable)

🔗 Related Issues

📸 Screenshots

📝 Additional Notes

[isbeorn]

the combobox should have the same alignment as the image source

[isbeorn]

The default entry is a bit odd. I would assume that you either have only one survey folder or one that is setup only with subfolders and not a mix.
To a user the default entry in the combobox might also be confusing - It makes sense internally as the backwards compatible fallback, but i would expect only my subfolders to be available when the cache is set up with multiple caches.

[naixx]

@isbeorn thanks for comment!

Default name can be probably odd, may be Root or anything other can fit.
My intention to have main directory with subdirectores are
a) backward compatibility. cache is also used in Sky Atlas screen. In case the user has "subdirs only solution" we have to provide a setting to choose main cache to be used in Sky Atlas
b) easier transition without migrations. I suppose many users already have FramingAssistantCache setup, and then we tell them "move you cache to a subdir and add other subdirs" but then what "sky survey setting folder" should point to? Can be misunderstanding there, IMO. Or we should provide migration script?
c) In case a user doesn't plan to add subfolders, do we force to move current default cache to subfolder?
d) I believe a fallback is required in case of emergency

May be a Tooltip can be added explaining what is Root or Default (with path or not). What do you think?
Also, currently I'm hiding combobox if subdirs are not detected. So that behavior is totally the same for all user. May be for transparency we should show it in all cases?

[isbeorn]

What i don't want is a mix of root level and sub folders for the cache. A migration should be easy to handle in case there is such a mix done.

I see these scenarios:

• No subfolders: Old behavior - no combobox shown
• Subfolders available:
  • Root level has cache and sub folders have cache
    • Move the root level into a new folder "Default"
  • Root level has no cache, but at least one sub folders has a cache
    • Show the subfolder names in the combobox

[naixx]

What i don't want is a mix of root level and sub folders for the cache.

Any specific reasons for this?

What about Sky Atlas?

[astroalex80]

Hi, as the creator of the additional sky caches based on the Northern Sky Narrowband Survey I had some thoughts on a possible integration as well.

Would it make sense under options to simply add 1-2 additional framing cache paths which in the framing assistant can be selected from the existing drop down like the regular sky cache?

[isbeorn]

What i don't want is a mix of root level and sub folders for the cache.

Any specific reasons for this?

What about Sky Atlas?

it's just a confusing setup for a user

[naixx]

@astroalex80 thanks for surveys!

As a user I wanted to have all of the surveys, I especially liked Ha and rgb versions. So having 8-9 paths in settings just to provide different surveys seed to me like an overkill. That's why I created this solution - just drop subdirs and forget. And you can manage which preview is shown is Sky Atlas by changing root dir, so that I can have narrowband previews in search.

Of course it can be done in more manageable way with migrations, metadata etc, but for me it's a matter of effort and winnings. Which I don't clearly see

[astroalex80]

Agree, keep it simple also as the creation of additional sky survey caches is quite unlikely due to missing sky survey sources with a reasonably large coverage and (visual) improvement over the existing cache. There are tons of surveys of course but not better than the DSS when it comes to visual spectrum. For narrowband there are even less sources.

For H-Alpha I am working on the MDW survey to make it available as an additional cache as it is of excellent quality and allsky. Of course, licence questions must be answered and permission be granted but giving the fact they are public available hosted by the Columbia University this shouldn't be a show stopper.

@daleghent the new (Northern Sky Narrowband Survey) caches include a licence txt file with clear description of their origin/source.

[daleghent]

The image cache packs seem to have something missing, and that is metadata about themselves. There is the CacheInfo.xml file that each must have but the information currently in that file pertains only to placing the cache's images in the sky. It lacks descriptive information about itself, such as its name, license, origin, and any other kind information about itself as a whole.

From a design and delivery standpoint, I think we have an opportunity to step back and reconsider the current design. Populating the combo box based on directory names that cache files live in seems rather unsophisticated. It's plausible that a user could place these cache files in a location that, combined with the name, busts Windows length limit on total paths and creating a situation where the user must contort the directory name (and thus the presented name) of the cache file directories just to get it to work.

I propose taking this opportunity to expand the existing CacheInfo.xml file to provide additional metadata:

• Proper name ("Northern Sky Narrowband Survey". "DSS/STScI survey", etc.)
• Long description of the cache pack
• License information (important as some data may demand it be distributed with license info. Can use SPDX codes)
• Cache pack version (following semantic versioning rules)
• Date+time of cache creation (ISO 8601 format)
• Cache pack author name and contact
• Cache pack website URL

Critical for this topic is the name of the cache pack. Not all of the above fields would be immediately used by NINA, but would at least be available to provide sufficient description, origin information, and license information to those who would look for it. That information would be present for a future "Image cache manager" to use, similar to the existing plugin manager. In fact, it may be useful to think of these image cache packs as a different type of NINA plugin.

The cache packs would still live under a root directory. Each one would be unzipped/unpacked directly into its own uniquely-named sub-directory off that root. I would suggest that sub-directory be a GUID or portion of a GUID (first or last 8 characters) to ensure non-interference with an unrelated cache pack.

Upon app startup, NINA's Framing Assistant would scan those directories and read contents of CacheInfo.xml to, at a minimum, get the name of the cache. It would then build an object for each cache that contains that name, file path, and any other info. This object would then be used in the combobox the Framing Assistant presents to the user to select the desired cache.

This would accomplish a few things:

• User experience will enhanced and normalized across different users by seeing consistent information about their installed caches
• Rich information about each image cache pack would already exist to facilitate the creation a possible future image cache manager
• The design can separate the storage mechanics of multiple cache packs from how they are presented to the user.

[naixx]

Rebased onto current develop

[isbeorn]

Sorry for the late reply, I just had the time today to give this another look.

I’d like the cache layout to be either the old single root cache, or multiple subfolder caches, but not a mix.

Requested changes:

• No subfolders: keep old behavior, no combobox.
• Subfolders exist: show only subfolder cache names in the SKYATLAS combobox.
• If root CacheInfo.xml has entries and subfolders exist, migrate all direct root files into Default; use Default (1), etc. on conflict.
• Do not migrate empty root CacheInfo.xml, and do not recreate root CacheInfo.xml in multi-cache mode.
• Reserve a User Cache folder for newly saved online/file cache entries.
• CACHE source should use only User Cache then in multi-cache mode.
• Exclude User Cache from the SKYATLAS selector.
• Rename VM properties to make the split clear, e.g. AvailableSkyAtlasCacheSources / SelectedSkyAtlasCacheSource.

The combobox alignment change looks good.

@daleghent I agree that richer cache-pack metadata would be useful later, but I'd keep that as a separate follow-up and keep this PR focused on fixing the cache layout and selection behavior.