@loveluthien/carta-frontend 6.0.0-dev

package/docs_website/versioned_docs/version-4.1.0/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/versioned_docs/version-4.1.0/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/versioned_docs/version-4.1.0/code-snippet-tutorial/image-fitting.mdx

@@ -0,0 +1,42 @@
+---
+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.showFittingDialog();
+
+// Clear previous inputs of initial values
+app.imageFittingStore.clearComponents();
+
+// Set initial values
+app.imageFittingStore.setComponents(2);
+
+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);
+
+// Fit the image
+app.imageFittingStore.fitImage();
+```

package/docs_website/versioned_docs/version-4.1.0/code-snippet-tutorial/image-properties.mdx

@@ -0,0 +1,86 @@
+---
+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 <ApiLink path="/.-models/enum/POLARIZATIONS">
+    `POLARIZATIONS`
+</ApiLink> 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 <ApiLink path="/.-stores/enum/FrameScaling">`FrameScaling`</ApiLink> 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/versioned_docs/version-4.1.0/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/versioned_docs/version-4.1.0/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/versioned_docs/version-4.1.0/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/#setActiveFrame">`setActiveFrame`</ApiLink>, as well as the wrapper functions <ApiLink path="/.-stores/class/AppStore/#setActiveFrameById">`setActiveFrameById`</ApiLink> and <ApiLink path="/.-stores/class/AppStore/#setActiveFrameByIndex">`setActiveFrameByIndex`</ApiLink>.
+
+```javascript
+app.setActiveFrameByIndex(0);
+app.setActiveFrameById(file2.frameInfo.fileId);
+app.setActiveFrame(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/versioned_docs/version-4.1.0/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/versioned_docs/version-4.1.0/contributing/_category_.json

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

package/docs_website/versioned_docs/version-4.1.0/contributing/developer-tips.md

@@ -0,0 +1,36 @@
+---
+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
+```

package/docs_website/versioned_docs/version-4.1.0/contributing/documentation-guidelines.md

@@ -0,0 +1,87 @@
+---
+sidebar_position: 4
+---
+
+# Documentation guidelines
+
+Guidelines for building and writing this website.
+
+## Building documentation
+
+The website is hosted on GitHub Pages, and whenever the `dev` branch is updated, the website is automatically updated using GitHub Actions.
+
+To build and test the website locally, navigate to the `docs_website/` directory and install package dependencies:
+
+```
+cd docs_website
+npm install
+```
+
+and run the development server:
+
+```
+npm start
+```
+
+If you make changes to the files in the `docs/` and `api/` folders, the site will automatically reload and display the changes.
+
+To create a local production build:
+
+```
+npm run build
+```
+
+To test the local production build:
+
+```
+npm run serve
+```
+
+Please note that the search feature is only available in production builds.
+
+## Writing documentation pages
+
+The "Docs" pages and the "API/Overview" page are generated from markdown files in the `docs/` and `api/` directories. Simply edit these directories to modify the content or add new pages.
+
+For links to the "Docs" index pages and "API" subpages, it is required to use the `DocsIndexLink` and `ApiLink` MDX components to ensure the corresponding version is linked. If the file contains MDX components, it is recommended to use the `.mdx` extension.
+
+### Formatting
+
+To check the format of the changes, run (from the `docs_website/` folder):
+
+```
+npm run checkformat
+```
+
+To automatically fix the format:
+
+```
+npm run reformat
+```
+
+This maintains consistent markdown styling, including indentation, maximum line length, and list numbering. Please refer to the [Prettier documentation](https://prettier.io/blog/2017/11/07/1.8.0.html#markdown-support) for more information.
+
+## Writing API documentation
+
+The "API" subpages are generated from TSDoc documentation in the codebase. Catalogs are created based on the `index.ts` files, and elements need to be exported in the respective `index.ts` file to appear on the catalog subpages. Private and projected elements are not displayed.
+
+Please note that the development server does not automatically re-parse TSDoc. Therefore, if you modify TSDoc in the codebase, you will need to rebuild it to display the changes.
+
+### Formatting
+
+For TSDoc format, please refer to the [TSDoc documentation](https://tsdoc.org). ESLint is applied to check for the required format. To run the lint checks (from the repository root):
+
+```
+npm run check-eslint
+```
+
+## Versioning
+
+To tag a new version, run (from the `docs_website/` folder):
+
+```
+npm run docusaurus docs:version 1.2.3
+npm run docusaurus api:version 1.2.3
+```
+
+This will append the new version to `versions.json` and create files in the `versioned_docs/` and `versioned_sidebars/` folders. To modify the content or add new pages for a specific version, edit the files in these folders.