Metadata-Version: 2.1
Name: vsui-client
Version: 1.1.5
Summary: Client module for connecting to Volume Segmantics User Inteface
Author: Matthew Pimblott
Author-email: matthew.pimblott@diamond.ac.uk
Requires-Python: >=3.9,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: matplotlib (>=3.6.1,<4.0.0)
Requires-Dist: python-socketio[client] (>=5.7.2,<6.0.0)
Description-Content-Type: text/markdown

# Volume Segmantics User Interface (Client)

This is the client package for VSUI. It provides an interface for interacting with the api of a VSUI server.

It is recommended to use the object-oriented interface, although use of the methods in *_vsui_client.py* is possible to directly interact with the server. Communication is via a socketio connection to the server. The client only pushes notifications to the server, and cannot receive communications beyond the initial setup.

## Example Use
```python
import logging
from vsui_client import vsui_process, vsui_init
```

vsui_process is a decorator that provides exception handling. Specifically, it catches all exceptions apart from *KeyboardInterrupt*, to communicate the error to the server before the process exits. This includes *SystemExit* exceptions raised by *sys.exit()*. This exception handling behavior will only occur in wrapped functions, otherwise errors will result in undefined behaviour with regard to UI user feedback.


#### Setup
```python
@vsui_process()
def entrypoint_to_my_process():
    logger = logging.get_logger()
    vsui_enabled = True
    process_id = 'my_process'
    logging_component_id = 'Logs'
    VSUI = init_vsui(vsui_enabled, process_id, logging_component_id)
    VSUI.connect()
    handler = VSUI.get_handler()
    logger.addHandler(handler)
```

### Use in other modules
To get your current instance of VSUI from another process, it is possible to import it from where it was initialised, but it is recommended to use the *vsui_client.get_client()* method instead. This will return a reference to the current instance.

```python
from vsui_client import get_client

VSUI = get_client()
```

### Interacting with the server
The VSUI server thinks in terms of processes, tasks and components. Your program wrapped by *@vsui_process*, and using an instance of *VSUIClient*, is an example of a process. This should generally be a long-running task which you want to allow a user to setup via a GUI, and receive ongoing feedback from. Consult the VSUI documentation for more information about how to define a process.

Use the VSUIClient class to interact with the server api. In the following documentation *VSUI* is in instance of VSUIClient.

#### connect()
This Initiates a connection to a vsui server on the given host and port. The connection is via a socket that remains open until manually disconnected, or the process closes.
```Python
VSUI.connnect(host: str = 'host', port: str = 'port')
```

#### disconnect()
Disconnect the client from the server.
```Python
VSUI.disconnect()
```

#### edit element()
This method allows you to update the data of a component on the server. The component must be defined in the process definition on the server. The data must be serialisable to json.

```Python
VSUI.edit_element(element_uid: str, value: dict | str)
```

#### deactivate_task()
This method allows you to signal to the server that the task should be deactivated.

```Python
VSUI.deactivate_task()
```

#### notify()
This method allows you to send a toast notification to the client. The notification will be displayed in a toast and will disappear after a short time.

available types:
- success
- error
- info
- warning

```Python
VSUI.notify(txt: str, type: str)
```

#### set_task_id()
This method allows you to set the task id of the process.

```Python
VSUI.set_task_id(id: str)
```

#### set_logging_target()
This method allows you to set the component key of the task element that logs should be forwarded to.

```Python
VSUI.set_logging_target(key: str)
```

#### get_handler()
This method allows you to get the logging handler that forwards logs to the server.

```Python
VSUI.get_handler()
```

#### encode_image()
This method allows you to encode an image to base64.

```Python
VSUI.encode_image(arr: np.ndarray, title: str, format: str, figsize: tuple, cmap: str)
```
