@loveluthien/carta-frontend 6.0.0-dev

package/declarations.d.ts

@@ -0,0 +1,18 @@
+declare module "*.png" {
+    const value: any;
+    export = value;
+}
+declare module "*.svg" {
+    const value: any;
+    export = value;
+}
+declare module "*.jpg" {
+    const value: any;
+    export = value;
+}
+
+declare module '*.glsl';
+declare module '*.frag';
+declare module '*.vert';
+
+declare module '!worker-loader*';

package/docs_website/.prettierignore

@@ -0,0 +1 @@
+versioned_docs/**/api-*.json

package/docs_website/api/api.md

@@ -0,0 +1,13 @@
+## Table of Contents
+
+-   <ApiLink path="/.-components"><h4>Components</h4></ApiLink>
+
+    -   <ApiLink path="/.-components/Dialogs"><h5>Components - Dialogs</h5></ApiLink>
+    -   <ApiLink path="/.-components/Shared"><h5>Components - Shared</h5></ApiLink>
+
+-   <ApiLink path="/.-enums"><h4>Enums</h4></ApiLink>
+-   <ApiLink path="/.-models"><h4>Models</h4></ApiLink>
+-   <ApiLink path="/.-services"><h4>Services</h4></ApiLink>
+-   <ApiLink path="/.-stores"><h4>Stores</h4></ApiLink>
+-   <ApiLink path="/.-utilities"><h4>Utilities</h4></ApiLink>
+-   <ApiLink path="/changelog"><h4>Changelog</h4></ApiLink>

package/docs_website/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+    presets: [require.resolve("@docusaurus/core/lib/babel/preset")]
+};

package/docs_website/docs/code-snippet-tutorial/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Code snippet tutorial",
+    "position": 2,
+    "link": {
+        "type": "generated-index",
+        "description": "Tutorials for the code snippet feature in CARTA frontend."
+    }
+}

package/docs_website/docs/code-snippet-tutorial/basics.md

@@ -0,0 +1,97 @@
+---
+sidebar_position: 2
+---
+
+# Basics
+
+Code snippets are regular ES6-based JavaScript (JS) code blocks.
+
+Lines starting with "//" are treated as comments. You can also comment in multiple lines using C-style comments.
+
+```javascript
+// Lines starting with "//" are treated as comments.
+/* you can also comment in
+ * multiple lines using C-style comments
+ */
+```
+
+To log to the development console, use `console.log`.
+
+```javascript
+console.log("hello world");
+```
+
+Variables can be defined using `let` (mutable) or `const` (immutable).
+
+```javascript
+let x = 1;
+const y = "hello world";
+x += 15;
+```
+
+## Functions
+
+Functions can be defined in a number of ways.
+
+```javascript
+function squared(x) {
+    return x * x;
+}
+
+// This is an arrow function
+const cubed = x => x * x * x;
+
+// This is an arrow function with a block of codes
+const sqrt = x => {
+    // You can use builtin JS library functions
+    return Math.sqrt(x);
+};
+```
+
+Functions can also be asynchronous. Any functions that wait for user input or interact with the backend will be asynchronous.
+
+```javascript
+function delay(time) {
+    return new Promise((resolve, reject) => {
+        if (time < 0) {
+            reject("Invalid delay duration");
+        } else {
+            setTimeout(resolve, time);
+        }
+    });
+}
+```
+
+You can `await` asynchronous functions within another async function, or at the top level.
+
+```javascript
+async function pauseForOneSecond() {
+    await delay(1000);
+    return true;
+}
+```
+
+Awaiting is necessary to ensure that return values can be used correctly. Compare the following outputs:
+
+```javascript
+console.log("Awaiting properly:");
+const resultWithAwait = await pauseForOneSecond();
+console.log(resultWithAwait);
+console.log();
+
+console.log("No await:");
+const resultWithoutAwait = pauseForOneSecond();
+console.log(resultWithoutAwait);
+console.log();
+```
+
+Asynchronous functions can also be used with promise syntax.
+
+```javascript
+delay(100).then(() => console.log("Looks promising"));
+delay(-100).catch(err => console.log(err));
+```
+
+Note that the response to the first "delay" call is printed after the second one, because execution is non-blocking.
+
+For more usages of ES6-based JavaScript, please refer to the features of the language.

package/docs_website/docs/code-snippet-tutorial/image-blending.mdx

@@ -0,0 +1,57 @@
+---
+sidebar_position: 8
+---
+
+# Image blending
+
+Actions related to color blended images.
+
+## Creating color blended images
+
+<ApiLink path="/.-stores/class/ImageViewConfigStore/#createColorBlending">`createColorBlending`</ApiLink> creates a color blended image with a base layer from the spatial reference image and at most nine other layers from the spatially matched
+images.
+
+```javascript
+// Open three images
+const file1 = await app.openFile("image_r.fits");
+const file2 = await app.appendFile("image_g.fits");
+const file3 = await app.appendFile("image_b.fits");
+
+// Match images
+file2.setSpatialReference(file1);
+file3.setSpatialReference(file1);
+
+// Create a color blended image
+const colorBlendingStore = app.imageViewConfigStore.createColorBlending();
+console.log(colorBlendingStore.frames.length); // 3
+```
+
+<ApiLink path="/.-stores/class/ImageViewConfigStore/#removeColorBlending">`removeColorBlending`</ApiLink> closes a color blended image.
+
+```javascript
+app.imageViewConfigStore.removeColorBlending(colorBlendingStore);
+```
+
+## Color blending configuration
+
+The configuration of the color blended image is accessible via <ApiLink path="/.-stores/class/ColorBlendingStore">`ColorBlendingStore`</ApiLink>.
+
+```javascript
+// Add a new layer
+const file4 = await app.appendFile(path, "new_image.fits");
+file4.setSpatialReference(file1);
+colorBlendingStore.addSelectedFrame(file4);
+
+// Delete a layer
+colorBlendingStore.deleteSelectedFrame(2); // The fourth layer (the third selected layer)
+
+// Set alpha
+colorBlendingStore.setAlpha(0, 0.5); // The base layer
+colorBlendingStore.setAlpha(1, 0.7); // The second layer
+```
+
+Render configuration of each layer can be modified using <ApiLink path="/.-stores/class/RenderConfigStore">`renderConfig`</ApiLink>. The configuration is synchronized with the loaded image.
+
+```javascript
+colorBlendingStore.frames[0].renderConfig.setColorMap("gray");
+```

package/docs_website/docs/code-snippet-tutorial/image-fitting.mdx

@@ -0,0 +1,44 @@
+---
+sidebar_position: 7
+---
+
+# Image fitting
+
+The process of fitting images with multiple Gaussians can be done using code snippets.
+
+The configuration for the fitting is accessible via <ApiLink path="/.-stores/class/ImageFittingStore">`ImageFittingStore`</ApiLink>. Example code:
+
+```javascript
+// Open an image
+const file = await app.openFile("[filename]");
+
+// Display the fitting widget
+app.dialogStore.showDialog("fitting-dialog");
+
+// Set the number of Gaussian components
+app.imageFittingStore.setComponents(2);
+
+// Option 1: Fit the image with auto generated initial values
+app.imageFittingStore.fitImage();
+
+// Option 2: Fit the image without auto generated initial values
+app.imageFittingStore.setIsAutoInitVal(false);
+
+const component1 = app.imageFittingStore.components[0];
+component1.setCenterX(128);
+component1.setCenterY(129);
+component1.setAmplitude(0.01);
+component1.setFwhmX(10);
+component1.setFwhmY(6);
+component1.setPa(36);
+
+const component2 = app.imageFittingStore.components[1];
+component2.setCenterX(135);
+component2.setCenterY(135);
+component2.setAmplitude(0.01);
+component2.setFwhmX(4);
+component2.setFwhmY(9);
+component2.setPa(40);
+
+app.imageFittingStore.fitImage();
+```

package/docs_website/docs/code-snippet-tutorial/image-properties.mdx

@@ -0,0 +1,84 @@
+---
+sidebar_position: 3
+---
+
+# Image properties
+
+Actions for modifying various properties of the image. In the following examples, we assume that an image is loaded as
+
+```javascript
+const file = await app.openFile("my_image.fits");
+```
+
+## Changing field of view
+
+The field of view can be adjusted using various functions within <ApiLink path="/.-stores/class/FrameStore">`FrameStore`</ApiLink>.
+
+<ApiLink path="/.-stores/class/FrameStore/#setCenter">`setCenter`</ApiLink> and <ApiLink path="/.-stores/class/FrameStore/#setCenterWcs">`setCenterWcs`</ApiLink> set the center of the image.
+
+```javascript
+// image coordinate
+file.setCenter([x position], [y position]);
+
+// world coordinate
+file.setCenterWcs("[x position, ex: 0:00:00.0615838925]", "[y position, ex: 29:59:59.1999990820]");
+```
+
+<ApiLink path="/.-stores/class/FrameStore/#fitZoom">`fitZoom`</ApiLink> zooms the image to fit the widget size.
+
+```javascript
+file.fitZoom();
+```
+
+<ApiLink path="/.-stores/class/FrameStore/#zoomToSizeX">`zoomToSize...`</ApiLink> functions zoom the image to a specific scale.
+
+```javascript
+// image coordinate
+file.zoomToSizeX([size in x direction]);
+file.zoomToSizeY([size in y direction]);
+
+// world coordinate
+file.zoomToSizeXWcs('[size in x direction, ex: 2.56"]');
+file.zoomToSizeYWcs('[size in y direction, ex: 2.56"]');
+```
+
+## Changing the channel and Stokes
+
+<ApiLink path="/.-stores/class/FrameStore/#setChannel">`setChannel`</ApiLink> changes the channel of the image.
+
+```javascript
+file.setChannel([channel]);
+```
+
+<ApiLink path="/.-stores/class/FrameStore/#setStokes">`setStokes`</ApiLink> and <ApiLink path="/.-stores/class/FrameStore/#setStokesByIndex">`setStokesByIndex`</ApiLink> change the stokes of the image using the polarization enum or the index.
+
+```javascript
+file.setStokes(2); // Stokes Q
+file.setStokesByIndex(2); // The third polarization shown in the animator widget
+```
+
+## Changing render configuration
+
+Render configuration can be modified using <ApiLink path="/.-stores/class/RenderConfigStore">`renderConfig`</ApiLink> within <ApiLink path="/.-stores/class/FrameStore">`FrameStore`</ApiLink>.
+
+<ApiLink path="/.-stores/class/RenderConfigStore/#setCustomScale">`setCustomScale`</ApiLink> and <ApiLink path="/.-stores/class/RenderConfigStore/#setPercentileRank">`setPercentileRank`</ApiLink> change the rendering range.
+
+```javascript
+file.renderConfig.setCustomScale([clip min], [clip max]);
+file.renderConfig.setPercentileRank(90); // Change to 90%
+```
+
+<ApiLink path="/.-stores/class/RenderConfigStore/#setScaling">`setScaling`</ApiLink> changes the scaling functions using the FrameScaling enum.
+
+```javascript
+file.renderConfig.setScaling(1); // Log
+```
+
+<ApiLink path="/.-stores/class/RenderConfigStore/#setColorMap">`setColorMap`</ApiLink> changes the color map using options in <ApiLink path="/.-stores/class/RenderConfigStore/#COLOR_MAPS_ALL">`COLOR_MAPS_ALL`</ApiLink> list, and <ApiLink path="/.-stores/class/RenderConfigStore/#setInverted">
+    `setInverted`
+</ApiLink> inverts the color map.
+
+```javascript
+file.renderConfig.setColorMap("gray");
+file.renderConfig.setInverted(true);
+```

package/docs_website/docs/code-snippet-tutorial/moment-images.mdx

@@ -0,0 +1,31 @@
+---
+sidebar_position: 5
+---
+
+# Moment images
+
+The process of generating moment images can be done using code snippets.
+
+The configuration for the generator is accessible via <ApiLink path="/.-stores/class/SpectralProfileWidgetStore">`SpectralProfileWidgetStore`</ApiLink>. Available moment types (as enum) can be found [here](https://carta-protobuf.readthedocs.io/en/latest/enums.html#moment). Example code:
+
+```javascript
+// Open an image
+const file = await app.openFile("[filename]");
+
+// Create a spectral profile settings widget
+app.widgetsStore.createFloatingSpectralProfilerWidget();
+app.widgetsStore.createFloatingSettingsWidget("", "spectral-profiler-0", "spectral-profiler");
+
+// Get the SpectralProfileWidgetStore object
+const spectralProfileWidget = app.widgetsStore.spectralProfileWidgets.get("spectral-profiler-0");
+
+// Navigate to the moments tab
+spectralProfileWidget.setSettingsTabId(3);
+
+// Modify the configuration using SpectralProfileWidgetStore
+spectralProfileWidget.clearSelectedMoments(); // remove default: integrated value of the spectrum
+spectralProfileWidget.selectMoment(0); // mean value of the spectrum
+
+// Generate a moment image
+spectralProfileWidget.requestMoment();
+```

package/docs_website/docs/code-snippet-tutorial/pv-images.mdx

@@ -0,0 +1,28 @@
+---
+sidebar_position: 6
+---
+
+# PV images
+
+The process of generating PV images can be done using code snippets.
+
+The configuration for the generator is accessible via <ApiLink path="/.-stores/class/PvGeneratorWidgetStore">`PvGeneratorWidgetStore`</ApiLink>. Example code:
+
+```javascript
+// Open an image
+const file = await app.openFile("[filename]");
+
+// Create a line region
+const region = await file.regionSet.addRegionAsync(1, [{x: [start x], y: [start y]}, {x: [end x], y: [end y]}]);
+
+// Create a pv generator widget
+app.widgetsStore.createFloatingPvGeneratorWidget();
+
+// Get the PvGeneratorWidgetStore object
+const pvGeneratorWidget = app.widgetsStore.pvGeneratorWidgets.get("pv-generator-0");
+
+// Generate a pv image
+pvGeneratorWidget.setFileId(file.frameInfo.fileId);
+pvGeneratorWidget.setRegionId(file.frameInfo.fileId, region.regionId);
+pvGeneratorWidget.requestPV();
+```

package/docs_website/docs/code-snippet-tutorial/quick-start.mdx

@@ -0,0 +1,82 @@
+---
+sidebar_position: 1
+---
+
+# Quick start
+
+## Enabling code snippets
+
+The code snippet feature can be enabled via the preferences dialog:
+
+<img src={require("../assets/enable-code-snippets.png").default} alt="Enable code snippets" width="500" />
+
+Once the code snippet feature is enabled, the "Snippets" option appears in the menu. This allows you to create and run code snippets, providing additional functionality to CARTA.
+
+## Loading images
+
+CARTA functions and objects can be accessed via the top-level <ApiLink path="/.-stores/class/AppStore">`app`</ApiLink> object (or the <ApiLink path="/.-stores/class/AppStore">`carta`</ApiLink> alias). In the following example, we display the welcome splash screen for 1000 ms and then close it.
+
+```javascript
+carta.showSplashScreen();
+await carta.delay(1000);
+app.hideSplashScreen();
+```
+
+Images loaded in the frontend are referred as and registered in the <ApiLink path="/.-stores/class/AppStore/#frames">`frames`</ApiLink> array which contains each frame (i.e., image) as a <ApiLink path="/.-stores/class/FrameStore">`FrameStore`</ApiLink> object. The currently active frame is accessible with <ApiLink path="/.-stores/class/AppStore/#activeFrame">`activeFrame`</ApiLink>. In the following example, we firstly list the frames array, then list the 0th frame, and finally list the current active frame in the console.
+
+```javascript
+console.log(app.frames);
+console.log(app.frames[0]);
+console.log(app.activeFrame);
+```
+
+<ApiLink path="/.-stores/class/AppStore/#openFile">`openFile`</ApiLink> takes up to three arguments: directory, filename and HDU. If no HDU is provided, the first HDU ("0") is adopted. The directory and filename can also be combined into a single
+argument. <ApiLink path="/.-stores/class/AppStore/#openFile">`openFile`</ApiLink> must be called with `await`, as it is an asynchronous function that requires communicating with the backend. In the following example, in the end we will see that
+only the last image is loaded as each <ApiLink path="/.-stores/class/AppStore/#openFile">`openFile`</ApiLink> will close all loaded image first before loading the target image.
+
+```javascript
+await app.openFile("test_directory", "testfile.fits", "0");
+await app.openFile("test_directory", "testfile.fits");
+await app.openFile("test_directory/testfile.fits");
+```
+
+Additional images can be appended using <ApiLink path="/.-stores/class/AppStore/#appendFile">`appendFile`</ApiLink>. The arguments are the same as <ApiLink path="/.-stores/class/AppStore/#openFile">`openFile`</ApiLink>. In the following example, in the end there will be three images loaded.
+
+```javascript
+const file1 = await app.openFile("testfile1.fits");
+const file2 = await app.appendFile("testfile2.fits");
+const file3 = await app.appendFile("testfile3.fits");
+```
+
+The active image can be changed with <ApiLink path="/.-stores/class/AppStore/#updateActiveImageByFrame">`updateActiveImageByFrame`</ApiLink>, as well as the wrapper functions <ApiLink path="/.-stores/class/AppStore/#setActiveImageByFileId">`setActiveImageByFileId`</ApiLink> and <ApiLink path="/.-stores/class/AppStore/#setActiveImageByIndex">`setActiveImageByIndex`</ApiLink>.
+
+```javascript
+app.setActiveImageByIndex(0);
+app.setActiveImageByFileId(file2.frameInfo.fileId);
+app.updateActiveImageByFrame(file3);
+```
+
+## Closing images
+
+<ApiLink path="/.-stores/class/AppStore/#closeCurrentFile">`closeCurrentFile`</ApiLink> closes the active image. There will be no user confirmation if the active image serves as the spatial reference image and there are other images matched
+to it.
+
+```javascript
+app.closeCurrentFile();
+```
+
+<ApiLink path="/.-stores/class/AppStore/#closeFile">`closeFile`</ApiLink> takes an optional boolean argument to control whether user confirmation is required if other images are matched to the given file. This defaults to true. `await` is required
+to delay execution until the user confirms.
+
+```javascript
+await app.closeFile(file1);
+app.closeFile(file1, false); // No user confirmation
+```
+
+<ApiLink path="/.-stores/class/AppStore/#closeOtherFiles">`closeOtherFiles`</ApiLink> closes all images other than the given file.
+
+```javascript
+app.closeOtherFiles(file2);
+```
+
+For all functions and objects available in the <ApiLink path="/.-stores/class/AppStore">`app`</ApiLink> object, please refer to the <ApiLink path="/.-stores/class/AppStore">API documentation</ApiLink>.

package/docs_website/docs/code-snippet-tutorial/regions.mdx

@@ -0,0 +1,49 @@
+---
+sidebar_position: 4
+---
+
+import Link from "@docusaurus/Link";
+
+# Regions
+
+Actions related to regions. In the following examples, we assume that an image is loaded as
+
+```javascript
+const file = await app.openFile("my_image.fits");
+```
+
+## Creating regions
+
+Regions on a specific image are accessible via <ApiLink path="/.-stores/class/RegionSetStore">`RegionSetStore`</ApiLink> under each image. Each region is represented by a <ApiLink path="/.-stores/class/RegionStore">`RegionStore`</ApiLink> object.
+
+```javascript
+console.log(file.regionSet.regions); // View all regions
+console.log(file.regionSet.selectedRegion); // View the selected region
+```
+
+<ApiLink path="/.-stores/class/RegionSetStore/#addRegionAsync">`addRegionAsync`</ApiLink> creates regions on the loaded image with available [region types](https://carta-protobuf.readthedocs.io/en/latest/enums.html#regiontype).
+
+```javascript
+const regionSet = file.regionSet;
+const region = await regionSet.addRegionAsync(3, [{x: [center x], y: [center y]}, {x: [width], y: [height]}]); // Add a rectangle region
+const region2 = await regionSet.addRegionAsync(1, [{x: [start x], y: [start y]}, {x: [end x], y: [end y]}]); // Add a line region
+```
+
+## Changing region properties
+
+Properties of a region can be modified using the <ApiLink path="/.-stores/class/RegionStore">`RegionStore`</ApiLink> object.
+
+```javascript
+// ex: a rectangle region
+region.setCenter({x: 0, y: 0}); // Move the region to position (0, 0)
+region.setSize({x: 100, y: 100}); // Resize to 100 x 100 pixels
+region.setColor("#ffffff"); // Change the color to white
+```
+
+## Importing regions
+
+<ApiLink path="/.-stores/class/AppStore/#importRegion">`importRegion`</ApiLink> imports regions to the active image with the provided path, filename, and [file type](https://carta-protobuf.readthedocs.io/en/latest/enums.html#filetype) enum.
+
+```javascript
+await app.importRegion("[path]", "[filename]", 1); // File type: CRTF
+```

package/docs_website/docs/contributing/_category_.json

@@ -0,0 +1,7 @@
+{
+    "label": "Contributing",
+    "position": 3,
+    "link": {
+        "type": "generated-index"
+    }
+}

package/docs_website/docs/contributing/developer-tips.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 1
+---
+
+# Developer tips
+
+Useful commands for development.
+
+## Checking and fixing code format
+
+To check the code format:
+
+```
+npm run checkformat
+```
+
+To automatically fix the code format:
+
+```
+npm run reformat
+```
+
+## Code linting
+
+ESLint is applied to identify program errors and to check for the format of imported packages and TSDoc documentation.
+To run the lint checks:
+
+```
+npm run check-eslint
+```
+
+To automatically fix the identified errors, particularly those related to import package formats:
+
+```
+npm run fix-eslint
+```
+
+## Git hooks
+
+This repository uses Husky and lint-staged to run checks automatically during commit and push.
+
+-   `pre-commit`: runs Prettier on staged files in `src/` (repo root Prettier) and on staged files in `docs_website/` using `docs_website/node_modules/.bin/prettier`, and runs ESLint auto-fix on staged JS/TS files in `src/`.
+-   `pre-push`: runs `npm run check-eslint` and `npm run checkformat`, and additionally runs `npm --prefix docs_website run checkformat` when pushed commits include `docs_website/` changes.
+
+Hooks are installed automatically when running:
+
+```
+npm install
+```
+
+If install scripts are skipped (for example, `npm ci --ignore-scripts`), run:
+
+```
+npm run prepare
+```
+
+If you modify files under `docs_website/`, make sure docs dependencies are installed first:
+
+```
+npm --prefix docs_website install
+```