@aguacerowx/javascript-sdk 0.0.16 → 0.0.20

package/src/satellite_support.js

@@ -0,0 +1,305 @@
+/**
+ * Satellite listing / timeline helpers aligned with aguacero-frontend (ActiveTimeContext + satelliteAvailability).
+ * Used by AguaceroCore for GOES-East WebGL satellite mode.
+ */
+
+export const SATELLITE_FRAMES_URL = 'https://rhnq3edhcry5n6nljn6my4o3h40zwxze.lambda-url.us-east-2.on.aws/';
+
+/** Same sector labels as production bundle / ActiveTimeContext SECTOR_CODE_MAP (inverse). */
+export const GOES_EAST_SATELLITE_SECTORS = [
+    'GOES-EAST CONUS',
+    'GOES-EAST FULL DISK',
+    'GOES-EAST MESOSCALE 1',
+    'GOES-EAST MESOSCALE 2',
+];
+
+/** Flat channel ids matching CHANNEL_CATEGORIES in frontend dictionaries. */
+export const GOES_SATELLITE_CHANNELS = [
+    ...['true_color', 'geocolor', 'ntmicro', 'day_cloud_phase', 'day_land_cloud_fire', 'air_mass', 'sandwich', 'simple_water_vapor', 'dust', 'fire_temperature'],
+    'C01', 'C02', 'C03', 'C04', 'C05', 'C06', 'C07', 'C08', 'C09', 'C10', 'C11', 'C12', 'C13', 'C14', 'C15', 'C16',
+];
+
+/**
+ * Human-readable labels for {@link GOES_SATELLITE_CHANNELS}, aligned with aguacero-frontend `CHANNEL_LABELS`.
+ */
+export const GOES_SATELLITE_CHANNEL_LABELS = {
+    true_color: 'True Color',
+    ntmicro: 'Night Microphysics',
+    day_cloud_phase: 'Day Cloud Phase',
+    day_land_cloud_fire: 'Natural Color Fire',
+    air_mass: 'Air Mass',
+    sandwich: 'Sandwich',
+    simple_water_vapor: 'Simple Water Vapor',
+    dust: 'Dust',
+    geocolor: 'Geocolor',
+    fire_temperature: 'Fire Temperature',
+    C01: 'Blue - Visible',
+    C02: 'Red - Visible',
+    C03: 'Veggie - Near IR',
+    C04: 'Cirrus - Near IR',
+    C05: 'Snow/Ice - Near IR',
+    C06: 'Cloud Particle - Near IR',
+    C07: 'Shortwave Window - IR',
+    C08: 'Upper-Level Water Vapor - IR',
+    C09: 'Mid-Level Water Vapor - IR',
+    C10: 'Lower-Level Water Vapor - IR',
+    C11: 'Cloud Top - IR',
+    C12: 'Ozone - IR',
+    C13: 'Clean Longwave Window - IR',
+    C14: 'Longwave Window - IR',
+    C15: 'Dirty Longwave Window - IR',
+    C16: 'CO2 Longwave - IR',
+};
+
+const SECTOR_CODE_MAP = {
+    'GOES-EAST CONUS': 'C',
+    'GOES-EAST FULL DISK': 'F',
+    'GOES-EAST MESOSCALE 1': 'M1',
+    'GOES-EAST MESOSCALE 2': 'M2',
+};
+
+const LUMPED_MULTIBAND_SATELLITE_SECTORS = new Set(['GOES-EAST CONUS', 'GOES-EAST FULL DISK']);
+
+/** Uppercase RGB channel tokens as in production (CHANNEL_CATEGORIES.RGB). */
+const SATELLITE_RGB_PRODUCT_UPPER = new Set([
+    'TRUE_COLOR',
+    'GEOCOLOR',
+    'NTMICRO',
+    'DAY_CLOUD_PHASE',
+    'DAY_LAND_CLOUD_FIRE',
+    'AIR_MASS',
+    'SANDWICH',
+    'SIMPLE_WATER_VAPOR',
+    'DUST',
+    'FIRE_TEMPERATURE',
+]);
+
+/**
+ * Allowed timeline window lengths (hours) for satellite and MRMS in the Web SDK.
+ * Values are stringified for state and API parity with satellite duration options.
+ */
+export const TIMELINE_DURATION_HOUR_VALUES = ['1', '4', '6', '12'];
+
+const LEGACY_SATELLITE_DURATION_ALIASES = {
+    '0.5': '1',
+};
+
+/** Tier keys used in SATELLITE_DURATION_CONFIG (frontend dictionaries). */
+export const SATELLITE_DURATION_CONFIG = {
+    CONUS: {
+        basic: [
+            { label: '1 Hr', value: '1', interval: 300 },
+            { label: '4 Hr', value: '4', interval: 300 },
+            { label: '6 Hr', value: '6', interval: 300 },
+            { label: '12 Hr', value: '12', interval: 300 },
+        ],
+    },
+    FULL_DISK: {
+        basic: [
+            { label: '1 Hr', value: '1', interval: 600 },
+            { label: '4 Hr', value: '4', interval: 600 },
+            { label: '6 Hr', value: '6', interval: 600 },
+            { label: '12 Hr', value: '12', interval: 600 },
+        ],
+    },
+    MESOSCALE: {
+        basic: [
+            { label: '1 Hr', value: '1', interval: 120 },
+            { label: '4 Hr', value: '4', interval: 120 },
+            { label: '6 Hr', value: '6', interval: 120 },
+            { label: '12 Hr', value: '12', interval: 120 },
+        ],
+    },
+};
+
+/**
+ * Normalizes satellite or MRMS duration option values (including legacy '0.5' → '1').
+ * @param {string|number} value
+ * @returns {string}
+ */
+export function normalizeTimelineDurationValue(value) {
+    const s = value == null ? '1' : String(value);
+    return LEGACY_SATELLITE_DURATION_ALIASES[s] || s;
+}
+
+/**
+ * @param {string|number} value
+ * @returns {number} Hours in [1, 4, 6, 12], defaulting to 1.
+ */
+export function parseTimelineDurationHours(value) {
+    const s = normalizeTimelineDurationValue(value);
+    const n = Number(s);
+    if (TIMELINE_DURATION_HOUR_VALUES.includes(s) && [1, 4, 6, 12].includes(n)) return n;
+    return 1;
+}
+
+export function getDefaultSatelliteDurationOption(sectorName, tier = 'basic') {
+    let sectorType = 'CONUS';
+    if (sectorName.includes('FULL DISK')) sectorType = 'FULL_DISK';
+    else if (sectorName.includes('MESOSCALE')) sectorType = 'MESOSCALE';
+    const tierConfig = SATELLITE_DURATION_CONFIG[sectorType]?.[tier] || SATELLITE_DURATION_CONFIG.CONUS.basic;
+    return tierConfig.find((o) => o.value === '1') || tierConfig[0];
+}
+
+export function calculateUnixTimeFromSatelliteKey(fileKey) {
+    try {
+        const match = fileKey.match(/_(\d{10})(?:\.ktx2)?$/);
+        if (match) return parseInt(match[1], 10);
+        const oldMatch = fileKey.match(/_s(\d{4})(\d{3})(\d{2})(\d{2})(\d{2})/);
+        if (oldMatch) {
+            const [, year, dayOfYear, hour, minute, second] = oldMatch.map(Number);
+            const date = new Date(Date.UTC(year, 0, 1));
+            date.setUTCDate(dayOfYear);
+            date.setUTCHours(hour, minute, second, 0);
+            return date.getTime() / 1000;
+        }
+        return 0;
+    } catch {
+        return 0;
+    }
+}
+
+/**
+ * @param {string} satelliteKey e.g. "GOES19-EAST.GOES-EAST CONUS.C13"
+ * @param {string[]} allFiles S3 keys from satellite listing API
+ * @param {{ value: string, interval: number }} durationOption
+ */
+export function buildSatelliteTimelineForKey(satelliteKey, allFiles, durationOption) {
+    const parts = satelliteKey.split('.');
+    if (parts.length < 3) {
+        return { unixTimes: [], fileList: [], timeToFileMap: {} };
+    }
+    const [satelliteName, categoryName, channelName] = parts;
+
+    const SECTOR_CODE_MAP_LOCAL = {
+        'GOES-EAST CONUS': 'C',
+        'GOES-EAST FULL DISK': 'F',
+        'GOES-EAST MESOSCALE 1': 'M1',
+        'GOES-EAST MESOSCALE 2': 'M2',
+    };
+
+    const satelliteNum = satelliteName.replace('GOES', '').replace('-EAST', '').replace('-WEST', '');
+    const satId = `G${satelliteNum}`;
+    const sectorCode = SECTOR_CODE_MAP_LOCAL[categoryName] || 'C';
+
+    let sectorType = 'CONUS';
+    if (categoryName.includes('FULL DISK')) sectorType = 'FULL_DISK';
+    else if (categoryName.includes('MESOSCALE')) sectorType = 'MESOSCALE';
+
+    const intervalSeconds = durationOption?.interval || 300;
+    const durationHours = durationOption?.value ? parseFloat(durationOption.value) : 1;
+
+    const filePrefix = `${sectorCode}_${satId}_`;
+
+    let searchProduct = channelName.toUpperCase();
+    if (!/^C\d{2}$/.test(searchProduct)) {
+        if (SATELLITE_RGB_PRODUCT_UPPER.has(searchProduct)) {
+            searchProduct = LUMPED_MULTIBAND_SATELLITE_SECTORS.has(categoryName) ? 'MULTI' : searchProduct;
+        } else {
+            searchProduct = 'MULTI';
+        }
+    }
+
+    const matchString = `${filePrefix}${searchProduct}`;
+
+    let relevantFiles = allFiles.filter((file) => file.startsWith(matchString));
+
+    if (relevantFiles.length === 0) {
+        return { unixTimes: [], fileList: [], timeToFileMap: {} };
+    }
+
+    relevantFiles.sort((a, b) => {
+        const timeA = calculateUnixTimeFromSatelliteKey(a);
+        const timeB = calculateUnixTimeFromSatelliteKey(b);
+        return timeA - timeB;
+    });
+
+    let cutoffTime = 0;
+    if (durationHours > 0) {
+        const latestTime = calculateUnixTimeFromSatelliteKey(relevantFiles[relevantFiles.length - 1]);
+        cutoffTime = latestTime - durationHours * 3600;
+    }
+
+    let processedFiles = relevantFiles.filter((f) => calculateUnixTimeFromSatelliteKey(f) >= cutoffTime);
+
+    if (intervalSeconds > 0 && processedFiles.length > 0) {
+        const intervalMinutes = intervalSeconds / 60;
+
+        if (sectorType === 'MESOSCALE') {
+            processedFiles = processedFiles.filter((file) => {
+                if (intervalMinutes <= 1.1) return true;
+                const t = calculateUnixTimeFromSatelliteKey(file);
+                const date = new Date(t * 1000);
+                const minutes = date.getUTCMinutes();
+                return minutes % intervalMinutes === 0;
+            });
+        } else {
+            if (intervalSeconds >= 300) {
+                processedFiles = processedFiles.filter((file) => {
+                    if (Math.abs(intervalMinutes - 5) < 0.1) return true;
+                    const t = calculateUnixTimeFromSatelliteKey(file);
+                    const minutes = new Date(t * 1000).getUTCMinutes();
+                    const remainder = minutes % intervalMinutes;
+                    const distToInterval = Math.min(remainder, intervalMinutes - remainder);
+                    return distToInterval < 2.5;
+                });
+            } else {
+                processedFiles = processedFiles.filter((file) => {
+                    const t = calculateUnixTimeFromSatelliteKey(file);
+                    const minutes = new Date(t * 1000).getUTCMinutes();
+                    return minutes % intervalMinutes === 0;
+                });
+            }
+        }
+
+        if (processedFiles.length === 0 && relevantFiles.length > 0) {
+            processedFiles = relevantFiles.slice(-1);
+        }
+    }
+
+    const unixTimes = [];
+    const timeToFileMap = {};
+    processedFiles.forEach((file) => {
+        const unixTime = calculateUnixTimeFromSatelliteKey(file);
+        if (unixTime > 0) {
+            unixTimes.push(unixTime);
+            timeToFileMap[unixTime] = file;
+        }
+    });
+
+    // Chronological (oldest → newest): matches standard time sliders (earlier left, later right).
+    unixTimes.sort((a, b) => a - b);
+
+    return { unixTimes, fileList: processedFiles, timeToFileMap };
+}
+
+/**
+ * Full satellite keys for GOES-19 East (same naming as production).
+ */
+export function getAllGoesEastSatelliteKeys(satelliteName = 'GOES19-EAST') {
+    const keys = [];
+    for (const sector of GOES_EAST_SATELLITE_SECTORS) {
+        for (const ch of GOES_SATELLITE_CHANNELS) {
+            keys.push(`${satelliteName}.${sector}.${ch}`);
+        }
+    }
+    return keys;
+}
+
+export function resolveSatelliteS3FileName(satelliteKey, timeToFileMap, satelliteTimestamp) {
+    const fileFromMap = timeToFileMap?.[satelliteTimestamp];
+    if (fileFromMap) return fileFromMap;
+    const [, , channelName] = satelliteKey.split('.');
+    const channelNameUpper = channelName.toUpperCase();
+    let name = fileFromMap || '';
+    if (!name && satelliteTimestamp != null) {
+        const suffix = `_${String(Math.floor(Number(satelliteTimestamp)))}`;
+        const multiName = Object.values(timeToFileMap || {}).find((f) => f.includes('MULTI') && f.includes(suffix));
+        if (multiName) {
+            name = multiName.replace('MULTI', channelNameUpper);
+        }
+    }
+    return name;
+}
+
+export { SECTOR_CODE_MAP };