xcube Viewer

A simple viewer component for xcube.

Run it

Note, there is no need to install xcube Viewer on its own. It is bundled with the xcube Python package since version 1.0. Just run

xcube serve -c server-config.yaml

and access the viewer via the server endpoint /viewer, hence http://127.0.0.1/viewer, when run without URL prefix.

For development or for independent deployment, please read ahead to

1. install xcube and run server in demo mode;
2. install and start xcube-viewer with demo configuration.

Install xcube in development mode

xcube one-time install:

$ git clone https://github.com/xcube-dev/xcube.git
$ cd xcube
$ conda env create
$ conda activate xcube
$ pip install -ve .  

xcube update and run server:

$ cd xcube
$ git pull
$ conda activate xcube  
$ xcube serve --verbose --traceperf --config xcube/examples/serve/demo/config.yml  

If errors occur, you may need to update the environment:

$ conda env update

Install and run xcube-viewer in development mode

Checkout xcube-viewer sources:

$ git clone https://github.com/xcube-dev/xcube-viewer.git
$ cd xcube-viewer
$ npm install
$ npm run dev

Update, install, and run:

$ cd xcube-viewer
$ git pull
$ npm install
$ npm run dev

Build xcube-viewer for deployment with default branding:

$ cd xcube-viewer
$ git pull
$ npm run build

Find outputs in ./dist.

Update xcube by a new xcube-viewer build

To bundle the xcube package with a new xcube-viewer version first build xcube-viewer as described above. Then, in the xcube repo checked out from GitHub replace the contents the xcube/webapi/viewer/data directory with the contents of the ./dist directory. Note, it is important to replace the contents, do not just copy. Finally, add new files to git and commit all changes.

Developer Guide

Code organisation

Given here are the top-level modules in the source code folder src:

Module	Content
actions/	Actions associated with different application states
api/	Server endpoint access functions
components/	Plain React components
connected/	Higher-level Rect components connected to Redux
hooks/	React hook functions
model/	Data model types and model-specific functions
reducers/	Redux reducer functions associated with different application states
resources/	Application JSON and image resources
selectors/	Selectors associated with with different application states
states/	All the application states
util/	Basic utility types and functions
volume/	Experimental volume rendering code
config	Application configuration access
index	Application entry point
version	Application version string

Styling

Use the sx property of MUI components. Avoid inline style objects. Instead, create a local module object styles

import { makeStyles } from "@/util/styles";

const styles = makeStyles({
  container: {
    display: "flex",
    flexDirection: "column",
  },
  ...
})

and use its properties in components

<Box sx={styles.container}>...</Box>

Installing Local Chartlets for Testing and Development

Chartlets is a software framework that allows websites developed with React to be extended by server-side UI contributions programmed in Python or other programming languages.

It is currently used in xcube-viewer to allow users to create and integrate their own personalized UI contributions into the application.

To install and integrate local Chartlets into the xcube-viewer for testing and development, follow these steps:

Step 1: Build and Link Chartlets

Navigate to the chartlets/chartlets.js/packages/lib directory and run:

  npm run build
  npm link

Step 2: Link Chartlets in xcube-viewer

In the xcube-viewer directory, link the local Chartlets package:

  npm link chartlets

Step 3: Resolve React Dependency

Back in the Chartlets directory, ensure compatibility by linking React from xcube-viewer:

  npm link ../../../../xcube-viewer/node_modules/react

NOTE: The command above assumes that you have chartlets and xcube-viewerinstalled at the same level in your filesystem. If not, please adjust the ../.

Step 4: Using Local Chartlets in xcube-viewer

Now, the local Chartlets package should be installed and available in your local xcube-viewer instance.

Make sure to remove the chartlets: "^..." dependency from package.json (which you can revert after you are done testing it locally)

Step 5: Reflecting Changes

Whenever you make changes to Chartlets, rebuild the package for updates to take effect:

  npm run build

Step 6: Cleanup

When you're done testing, it's a good idea to unlink the packages to restore the original setup:

  cd xcube-viewer
  npm unlink chartlets
  cd ../chartlets/chartlets.js/packages/lib
  npm unlink chartlets

Unlinking helps prevent potential conflicts or unexpected behavior when switching back to the regular (non-linked) versions of the packages.

Now, you can revert your changes to package.json to bring back the chartlets dependency.

This setup above ensures smooth integration and quick iteration during development.

More

• User Guide
• Planned Enhancements
• Known Issues

---

This project was bootstrapped with React + TypeScript + Vite.

This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.

Currently, two official plugins are available:

• @vitejs/plugin-react uses Babel for Fast Refresh
• @vitejs/plugin-react-swc uses SWC for Fast Refresh

Expanding the ESLint configuration

If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:

• Configure the top-level parserOptions property like this:

export default {
  // other rules...
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
    project: ['./tsconfig.json', './tsconfig.node.json'],
    tsconfigRootDir: __dirname,
  },
}

• Replace plugin:@typescript-eslint/recommended to plugin:@typescript-eslint/recommended-type-checked or plugin:@typescript-eslint/strict-type-checked
• Optionally add plugin:@typescript-eslint/stylistic-type-checked
• Install eslint-plugin-react and add plugin:react/recommended & plugin:react/jsx-runtime to the extends list

Documentation

The xcube-viewer documentation is built using the mkdocs tool.

Create a Python environment and install the following packages:

• mkdocs
• mkdocs-material
• mkdocs-autorefs

#With repository root as current working directory:

To test local

mkdocs serve

To deploy on GitHub Pages

git checkout main
git pull 

mkdocs gh-deploy