Skip to content

Python API Reference

Here is the complete API reference for controlling FViewer from Python.

fviewer.api.FViewer

Bases: ImageControlMixin, RegionsMixin, DataCubeMixin

A Python client to control the FViewer browser-based application.

This class allows users to programmatically load files, adjust UI settings (colormaps, stretches), and manage regions via a REST API to the FViewer backend.

Attributes:

Name Type Description
base_url str

The base URL of the FastAPI backend.
headers dict

HTTP headers for authentication (e.g., Jupyter token).
client_id str

The specific browser client ID to control. If None, it will auto-connect to the first available client.
Source code in fviewer/api.py 
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
class FViewer(ImageControlMixin, RegionsMixin, DataCubeMixin):
    """
    A Python client to control the FViewer browser-based application.

    This class allows users to programmatically load files, adjust UI
    settings (colormaps, stretches), and manage regions via a REST API
    to the FViewer backend.

    Attributes:
        base_url (str): The base URL of the FastAPI backend.
        headers (dict): HTTP headers for authentication (e.g., Jupyter token).
        client_id (str): The specific browser client ID to control. If None,
                         it will auto-connect to the first available client.
    """

    def __init__(
        self,
        host: Optional[str] = None,
        port: Optional[int] = None,
        base_url: Optional[str] = None,
        client_id: Optional[str] = None,
    ):
        """
        Initializes the FViewer client connection.

        Args:
            host (str, optional): The hostname for the FViewer server.
            port (int, optional): The port for the FViewer server.
            base_url (str, optional): A direct URL to the API (useful for
                                      remote JupyterLab environments).
            client_id (str, optional): Target a specific connected browser tab.
        """
        default_url = 'http://127.0.0.1:8000/api'
        if base_url is not None:
            self.base_url = base_url
        elif host is None or port is None:
            # check environment variables in case we are inside jupyterlab
            url = os.environ.get('JUPYTER_SERVER_URL')
            if url is None:
                url = os.environ.get('JUPYTERHUB_SERVICE_URL')
            if url is None:
                # fall back to the default
                self.base_url = default_url
            else:
                self.base_url = urljoin(url, 'fviewer/api')
        else:
            self.base_url = f"http://{host}:{port}/api"

        self.headers = {}
        token = os.environ.get("JUPYTERHUB_API_TOKEN", None)
        if token is not None:
            self.headers["Authorization"] = f"token {token}"

        self.client_id = client_id

    def get_clients(self) -> List[str]:
        """
        Retrieves a list of all currently connected frontend browser
        client IDs.

        Returns:
            List[str]: A list of active client IDs.

        Raises:
            requests.exceptions.HTTPError: If the backend request fails.
        """
        response = requests.get(
            f"{self.base_url}/clients", headers=self.headers
        )
        response.raise_for_status()
        return response.json()["clients"]

    def wait_for_ready(
        self, timeout: int = 15, poll_interval: float = 0.5
    ) -> bool:
        """
        Blocks execution until the FViewer FastAPI server is running and a
        browser client has connected via WebSocket.

        Args:
            timeout (int): Maximum time to wait in seconds. Defaults to 15.
            poll_interval (float): Time between checks. Defaults to 0.5.

        Returns:
            bool: True if the server and client are ready.

        Raises:
            TimeoutError: If no browser client connects within the timeout.
        """
        start_time = time.time()
        server_up = False

        print("Waiting for FViewer to initialize...")

        while time.time() - start_time < timeout:
            if not server_up:
                try:
                    response = requests.get(
                        f"{self.base_url}/health",
                        timeout=1,
                        headers=self.headers,
                    )
                    if response.status_code == 200:
                        print("Server is running ...")
                        server_up = True
                except requests.exceptions.RequestException:
                    pass  # Server not up yet, keep looping

            if server_up:
                print("Checking for any display client ...")
                try:
                    clients = self.get_clients()
                    if len(clients) != 0:
                        self.client_id = clients[0]
                        print(
                            "Ready! Auto-connected to display client: "
                            f"{self.client_id}"
                        )
                        return True
                except Exception:
                    pass  # Keep looping until client appears

            time.sleep(poll_interval)

        raise TimeoutError(
            f"FViewer timed out after {timeout} seconds waiting "
            "for the browser to connect."
        )

    def _send(self, action: str, **kwargs) -> Dict[str, Any]:
        """
        Internal helper method to send command payloads to the backend server.

        Args:
            action (str): The command action to perform.
            **kwargs: Additional parameters required by the specific action.

        Returns:
            Dict[str, Any]: The JSON response from the server.

        Raises:
            RuntimeError: If no browser is connected or a 400 error occurs.
        """
        if not self.client_id:
            clients = self.get_clients()
            if not clients:
                raise RuntimeError(
                    "No browser connected! Please open "
                    "http://127.0.0.1:8000 in your browser first."
                )
            self.client_id = clients[0]
            print(f"Auto-connected to display client: {self.client_id}")

        payload = {"action": action, **kwargs}
        params = {"client_id": self.client_id}

        response = requests.post(
            f"{self.base_url}/command",
            json=payload,
            params=params,
            headers=self.headers,
        )

        if response.status_code == 400:
            err = response.json().get("detail", "Unknown error")
            raise RuntimeError(f"FViewer Error: {err}")

        response.raise_for_status()
        return response.json()

    def load_file(self, path: str) -> Dict[str, Any]:
        """Loads a FITS file into the viewer."""
        return self._send("load_file", path=path)

__init__(host=None, port=None, base_url=None, client_id=None)

Initializes the FViewer client connection.

Parameters:

Name Type Description Default
host str

The hostname for the FViewer server.

 None
port int

The port for the FViewer server.

 None
base_url str

A direct URL to the API (useful for remote JupyterLab environments).

 None
client_id str

Target a specific connected browser tab.

 None
Source code in fviewer/api.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def __init__(
    self,
    host: Optional[str] = None,
    port: Optional[int] = None,
    base_url: Optional[str] = None,
    client_id: Optional[str] = None,
):
    """
    Initializes the FViewer client connection.

    Args:
        host (str, optional): The hostname for the FViewer server.
        port (int, optional): The port for the FViewer server.
        base_url (str, optional): A direct URL to the API (useful for
                                  remote JupyterLab environments).
        client_id (str, optional): Target a specific connected browser tab.
    """
    default_url = 'http://127.0.0.1:8000/api'
    if base_url is not None:
        self.base_url = base_url
    elif host is None or port is None:
        # check environment variables in case we are inside jupyterlab
        url = os.environ.get('JUPYTER_SERVER_URL')
        if url is None:
            url = os.environ.get('JUPYTERHUB_SERVICE_URL')
        if url is None:
            # fall back to the default
            self.base_url = default_url
        else:
            self.base_url = urljoin(url, 'fviewer/api')
    else:
        self.base_url = f"http://{host}:{port}/api"

    self.headers = {}
    token = os.environ.get("JUPYTERHUB_API_TOKEN", None)
    if token is not None:
        self.headers["Authorization"] = f"token {token}"

    self.client_id = client_id

get_clients()

Retrieves a list of all currently connected frontend browser client IDs.

Returns:

Type Description
List[str]

List[str]: A list of active client IDs.

Raises:

Type Description
HTTPError

If the backend request fails.
Source code in fviewer/api.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
def get_clients(self) -> List[str]:
    """
    Retrieves a list of all currently connected frontend browser
    client IDs.

    Returns:
        List[str]: A list of active client IDs.

    Raises:
        requests.exceptions.HTTPError: If the backend request fails.
    """
    response = requests.get(
        f"{self.base_url}/clients", headers=self.headers
    )
    response.raise_for_status()
    return response.json()["clients"]

load_file(path)

Loads a FITS file into the viewer.

Source code in fviewer/api.py 
185
186
187
def load_file(self, path: str) -> Dict[str, Any]:
    """Loads a FITS file into the viewer."""
    return self._send("load_file", path=path)

wait_for_ready(timeout=15, poll_interval=0.5)

Blocks execution until the FViewer FastAPI server is running and a browser client has connected via WebSocket.

Parameters:

Name Type Description Default
timeout int

Maximum time to wait in seconds. Defaults to 15.

 15
poll_interval float

Time between checks. Defaults to 0.5.

 0.5

Returns:

Name Type Description
bool bool

True if the server and client are ready.

Raises:

Type Description
TimeoutError

If no browser client connects within the timeout.
Source code in fviewer/api.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def wait_for_ready(
    self, timeout: int = 15, poll_interval: float = 0.5
) -> bool:
    """
    Blocks execution until the FViewer FastAPI server is running and a
    browser client has connected via WebSocket.

    Args:
        timeout (int): Maximum time to wait in seconds. Defaults to 15.
        poll_interval (float): Time between checks. Defaults to 0.5.

    Returns:
        bool: True if the server and client are ready.

    Raises:
        TimeoutError: If no browser client connects within the timeout.
    """
    start_time = time.time()
    server_up = False

    print("Waiting for FViewer to initialize...")

    while time.time() - start_time < timeout:
        if not server_up:
            try:
                response = requests.get(
                    f"{self.base_url}/health",
                    timeout=1,
                    headers=self.headers,
                )
                if response.status_code == 200:
                    print("Server is running ...")
                    server_up = True
            except requests.exceptions.RequestException:
                pass  # Server not up yet, keep looping

        if server_up:
            print("Checking for any display client ...")
            try:
                clients = self.get_clients()
                if len(clients) != 0:
                    self.client_id = clients[0]
                    print(
                        "Ready! Auto-connected to display client: "
                        f"{self.client_id}"
                    )
                    return True
            except Exception:
                pass  # Keep looping until client appears

        time.sleep(poll_interval)

    raise TimeoutError(
        f"FViewer timed out after {timeout} seconds waiting "
        "for the browser to connect."
    )