Metadata-Version: 2.4
Name: tiled-qt
Version: 0.2.1
Summary: A PyQt5-based GUI client for Tiled
Author-email: Devin Burke <devin.burke@desy.de>
License: BSD 3-Clause License
        
        Copyright (c) 2026 Devin Burke
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are
        met:
        
        1. Redistributions of source code must retain the above copyright
            notice, this list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright
            notice, this list of conditions and the following disclaimer in the
            documentation and/or other materials provided with the
            distribution.
        
        3. Neither the name of the copyright holder nor the names of its
            contributors may be used to endorse or promote products derived
            from this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
        CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED
        WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
        PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
        THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
        DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
        PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
        USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
        HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
        IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
        NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
        USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
        OF SUCH DAMAGE.
        
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyQt5<6,>=5.15.11
Requires-Dist: numpy<3,>=2.4.3
Requires-Dist: pandas<4,>=3.0.2
Requires-Dist: matplotlib<4,>=3.10.8
Requires-Dist: tiled[client]<0.3,>=0.2.9
Requires-Dist: openpyxl<4,>=3.1.5
Requires-Dist: pyarrow<=23.0.1,>=19.0.0
Dynamic: license-file

# Tiled Qt

A modern desktop GUI client for the [Tiled](https://blueskyproject.io/tiled/) scientific data service, built with PyQt5 and Matplotlib.

## Features

- **Connect** to any Tiled server (public demo, local, or institutional).
- **Browse** the data tree with lazy-loading and efficient pagination.
- **Metadata Viewer**: Inspect nested metadata in a hierarchical tree view.
- **Array Visualization**: Plot 1D arrays, 2D images, and 3D slices with Matplotlib.
- **Table Viewer**: Browse DataFrames with a scrollable grid view, optimized for large datasets.
- **Advanced Search**: Query metadata using Key-Value pairs, Full Text, and Regex.
- **Export**: Save data and containers to HDF5, CSV, Excel, Parquet, PNG, TIFF, NumPy, and more.
- **Dynamic Format Discovery**: Export options are automatically filtered based on what the Tiled server supports for each specific item.
- **On-Demand Loading**: Fetch data only when needed, with support for remote slicing.
- **Navigation**: Full history support (Back/Forward) and breadcrumb navigation.
- **Security**: Safe slice parsing (no `eval`) and non-interactive authentication.

## Installation

### Using Pixi (Recommended)

If you have [Pixi](https://pixi.sh) installed, you can run the application directly:

```bash
pixi run tiled-qt
```

To run in debug mode:
```bash
pixi run tiled-qt debug
```

### Using Pip

You can install the package in editable mode from the source:

```bash
pip install -e .
```

This will provide the `tiled-qt` command in your environment.

### Using Rattler (Conda/Conda-forge)

The project includes a `recipe.yaml` for building a conda package using `rattler-build`:

```bash
rattler-build build --recipe recipe.yaml --target-platform linux-64
```

## Usage

After installation, simply run:

```bash
tiled-qt
```

### Quick Start

1.  **Connect**: Click **⚡ Connect** or press `Ctrl+K`.
2.  **Select Server**: Use the **NSLS-II Demo** preset or enter your server URL.
3.  **Browse**: Navigate the tree on the left. Containers load children lazily.
4.  **Inspect**: Click an item to view its metadata and basic information.
5.  **Visualize**: Click **Load Data** or **Load Table** to fetch and display the data.
6.  **Slicing**: For large arrays, enter a slice (e.g., `0, :, :`) before loading.
7.  **Export**: Right-click on a tree node or use the **Export** button in viewers. The available formats (HDF5, CSV, PNG, etc.) are dynamically discovered from the server.
8.  **Search**: Use the **Search** tab to find specific data by metadata.

## Development

The project is structured as a modular Python package:

- `src/tiled_qt/app.py`: Main application window and logic.
- `src/tiled_qt/widgets/`: Specialized UI components (Viewers, Search, etc.).
- `src/tiled_qt/styles.py`: UI styling and themes.
- `src/tiled_qt/utils.py`: Logging and helper functions.

### Running with a package manager

```bash
# Using Pixi
pixi run tiled-qt

# Using standard Python
python3 -m tiled_qt
```

## Demo Server

You can test the application using the NSLS-II public demo server:
`https://tiled-demo.nsls2.bnl.gov` (No login required).

## License

This project is licensed under the BSD 3-Clause License.
