# image-slide
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
A comprehensive Python image viewer for multidimensional numpy arrays with interactive controls for navigation, contrast adjustment, and complex data visualization.
## Features
### Core Functionality
- **Multi-dimensional array support**: View numpy arrays of arbitrary dimensions and shapes
- **Image navigation**: Slider-based navigation through image stacks
- **Complex array support**: Display magnitude, phase, real, or imaginary parts
- **Interactive controls**: Contrast, brightness, and colormap adjustment
- **Keyboard shortcuts**: Fast navigation with arrow keys
- **Professional interface**: Compact layout with all controls accessible
### Display Controls
- **Contrast adjustment**: 0.1x to 3.0x multiplication
- **Brightness adjustment**: -1.0 to +1.0 offset
- **Colormap selection**: 11 built-in colormaps (gray, viridis, plasma, etc.)
- **Auto-contrast**: Automatic contrast adjustment based on percentiles
- **Reset function**: Restore all settings to defaults
### Navigation
- **Mouse**: Use the slider to navigate between images
- **Keyboard shortcuts**:
- `←/→`: Previous/next image
- `Page Up/Down`: Jump by 10 images
- `Home/End`: Go to first/last image
## Installation
### From PyPI (when published)
```bash
pip install image-slide
```
### From Source
```bash
git clone https://github.com/GyroTools/image-slide.git
cd image-slide
pip install -e .
```
### Dependencies
- Python 3.8+
- numpy >= 1.19.0
- matplotlib >= 3.3.0
## Quick Start
### Basic Usage
```python
import numpy as np
from image_slide import ImageSlideViewer
# Create or load your numpy array of arbitrary shape
image_stack = np.random.random((10, 100, 100))
# Create and run viewer
viewer = ImageSlideViewer(image_stack, "My Images")
viewer.run()
```
### Convenience Function
```python
from image_slide import image_slide
# Even simpler - direct function call
image_slide(image_stack, "My Images")
```
### Complex Arrays
```python
# Complex array example
n_images, height, width = 5, 100, 100
complex_stack = np.random.random((n_images, height, width)) + 1j * np.random.random((n_images, height, width))
viewer = ImageSlideViewer(complex_stack, "Complex Data")
viewer.run()
```
### Loading from Files
```python
# Load from numpy file
data = np.load('your_data.npy')
image_slide(data, "Loaded Data")
# Load multiple images into stack
import glob
from PIL import Image
files = glob.glob("*.png")
images = [np.array(Image.open(f)) for f in files]
image_stack = np.array(images)
image_slide(image_stack, "Image Stack")
```
## Input Requirements
### Data Types
- **Real arrays**: Any numeric numpy dtype (int, float, etc.)
- **Complex arrays**: `complex64`, `complex128` with magnitude/phase/real/imaginary display options
- **Normalized**: Data is automatically normalized for display
## Advanced Usage
### Complex Array Display Modes
When working with complex arrays, you can choose what to display:
1. **Magnitude**: `|z|` - Shows the amplitude
2. **Phase**: `arg(z)` - Shows the phase angle
3. **Real**: `Re(z)` - Shows the real part
4. **Imaginary**: `Im(z)` - Shows the imaginary part
### Programmatic Control
```python
# Create viewer but don't show immediately
viewer = ImageSlideViewer(image_stack, "My Images")
# Set initial display parameters
viewer.contrast = 1.5
viewer.brightness = 0.2
viewer.current_complex_display = "phase" # for complex arrays
# Update display and show
viewer.update_display()
viewer.run()
```
### Keyboard Shortcuts Reference
| Key | Action |
|-----|--------|
| `←` | Previous image |
| `→` | Next image |
| `Page Up` | Jump back 10 images |
| `Page Down` | Jump forward 10 images |
| `Home` | Go to first image |
| `End` | Go to last image |
## Interface Components
- **Top Controls**: Contrast, brightness, colormap, and action buttons arranged horizontally
- **Image Display**: Central area with no borders, maximum space utilization
- **Bottom Navigation**: Image slider and index display
- **Status Bar**: Min/max values and data type information
## Examples
### Scientific Data Visualization
```python
import numpy as np
from image_slide import image_slide
# Simulate time series data
t = np.linspace(0, 4*np.pi, 50)
x, y = np.meshgrid(np.linspace(0, 2*np.pi, 100), np.linspace(0, 2*np.pi, 100))
time_series = np.array([np.sin(x + t[i]) * np.cos(y + t[i]) for i in range(len(t))])
image_slide(time_series, "Time Series Visualization")
```
### Medical Imaging
```python
# Simulate medical image stack (e.g., CT slices)
slices = np.random.random((30, 256, 256))
# Add some structure
for i, slice_img in enumerate(slices):
slices[i] = gaussian_filter(slice_img, sigma=2)
image_slide(slices, "Medical Image Stack")
```
### Fourier Transform Analysis
```python
# Create test pattern and its FFT
pattern = np.sin(2*np.pi*x*3) * np.cos(2*np.pi*y*2)
fft_data = np.fft.fftshift(np.fft.fft2(pattern))
# Stack original and FFT for comparison
combined = np.array([pattern, np.abs(fft_data), np.angle(fft_data)])
image_slide(combined, "FFT Analysis")
```
## Command Line Usage
The package is designed to be used as a Python library. Import and use the viewer in your Python scripts as shown in the examples above.
## Development
### Setting up Development Environment
```bash
git clone https://github.com/GyroTools/image-slide.git
cd image-slide
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
```
### Code Formatting
```bash
black image_slide/
```
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Changelog
### Version 1.0.0
- Initial release
- Basic image navigation and display
- Complex array support
- Contrast and brightness controls
- Multiple colormap options
- Keyboard shortcuts
- Professional compact interface
## Acknowledgments
- Built with [matplotlib](https://matplotlib.org/) for image display
- Uses [tkinter](https://docs.python.org/3/library/tkinter.html) for GUI
- Inspired by scientific image analysis workflows
## Support
- Create an [issue](https://github.com/GyroTools/image-slide/issues) for bug reports
- Start a [discussion](https://github.com/GyroTools/image-slide/discussions) for questions
- Check the [documentation](https://github.com/GyroTools/image-slide#readme) for usage examples
Raw data
{
"_id": null,
"home_page": null,
"name": "image-slide",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Martin Buehrer <martin.buehrer@gyrotools.com>",
"keywords": "image, viewer, numpy, matplotlib, scientific, visualization",
"author": null,
"author_email": "Martin Buehrer <martin.buehrer@gyrotools.com>",
"download_url": "https://files.pythonhosted.org/packages/c6/37/377d641d500297056b473fcff592d8d71543a68adbf37c5e2e6d94855bd2/image_slide-1.0.1.tar.gz",
"platform": null,
"description": "# image-slide\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nA comprehensive Python image viewer for multidimensional numpy arrays with interactive controls for navigation, contrast adjustment, and complex data visualization.\n\n\n\n## Features\n\n### Core Functionality\n- **Multi-dimensional array support**: View numpy arrays of arbitrary dimensions and shapes\n- **Image navigation**: Slider-based navigation through image stacks\n- **Complex array support**: Display magnitude, phase, real, or imaginary parts\n- **Interactive controls**: Contrast, brightness, and colormap adjustment\n- **Keyboard shortcuts**: Fast navigation with arrow keys\n- **Professional interface**: Compact layout with all controls accessible\n\n### Display Controls\n- **Contrast adjustment**: 0.1x to 3.0x multiplication\n- **Brightness adjustment**: -1.0 to +1.0 offset\n- **Colormap selection**: 11 built-in colormaps (gray, viridis, plasma, etc.)\n- **Auto-contrast**: Automatic contrast adjustment based on percentiles\n- **Reset function**: Restore all settings to defaults\n\n### Navigation\n- **Mouse**: Use the slider to navigate between images\n- **Keyboard shortcuts**:\n - `\u2190/\u2192`: Previous/next image\n - `Page Up/Down`: Jump by 10 images\n - `Home/End`: Go to first/last image\n\n## Installation\n\n### From PyPI (when published)\n```bash\npip install image-slide\n```\n\n### From Source\n```bash\ngit clone https://github.com/GyroTools/image-slide.git\ncd image-slide\npip install -e .\n```\n\n### Dependencies\n- Python 3.8+\n- numpy >= 1.19.0\n- matplotlib >= 3.3.0\n\n## Quick Start\n\n### Basic Usage\n\n```python\nimport numpy as np\nfrom image_slide import ImageSlideViewer\n\n# Create or load your numpy array of arbitrary shape\nimage_stack = np.random.random((10, 100, 100))\n\n# Create and run viewer\nviewer = ImageSlideViewer(image_stack, \"My Images\")\nviewer.run()\n```\n\n### Convenience Function\n\n```python\nfrom image_slide import image_slide\n\n# Even simpler - direct function call\nimage_slide(image_stack, \"My Images\")\n```\n\n### Complex Arrays\n\n```python\n# Complex array example\nn_images, height, width = 5, 100, 100\ncomplex_stack = np.random.random((n_images, height, width)) + 1j * np.random.random((n_images, height, width))\n\nviewer = ImageSlideViewer(complex_stack, \"Complex Data\")\nviewer.run()\n```\n\n### Loading from Files\n\n```python\n# Load from numpy file\ndata = np.load('your_data.npy')\nimage_slide(data, \"Loaded Data\")\n\n# Load multiple images into stack\nimport glob\nfrom PIL import Image\n\nfiles = glob.glob(\"*.png\")\nimages = [np.array(Image.open(f)) for f in files]\nimage_stack = np.array(images)\nimage_slide(image_stack, \"Image Stack\")\n```\n\n## Input Requirements\n\n### Data Types\n- **Real arrays**: Any numeric numpy dtype (int, float, etc.)\n- **Complex arrays**: `complex64`, `complex128` with magnitude/phase/real/imaginary display options\n- **Normalized**: Data is automatically normalized for display\n\n## Advanced Usage\n\n### Complex Array Display Modes\n\nWhen working with complex arrays, you can choose what to display:\n\n1. **Magnitude**: `|z|` - Shows the amplitude\n2. **Phase**: `arg(z)` - Shows the phase angle \n3. **Real**: `Re(z)` - Shows the real part\n4. **Imaginary**: `Im(z)` - Shows the imaginary part\n\n### Programmatic Control\n\n```python\n# Create viewer but don't show immediately\nviewer = ImageSlideViewer(image_stack, \"My Images\")\n\n# Set initial display parameters\nviewer.contrast = 1.5\nviewer.brightness = 0.2\nviewer.current_complex_display = \"phase\" # for complex arrays\n\n# Update display and show\nviewer.update_display()\nviewer.run()\n```\n\n### Keyboard Shortcuts Reference\n\n| Key | Action |\n|-----|--------|\n| `\u2190` | Previous image |\n| `\u2192` | Next image |\n| `Page Up` | Jump back 10 images |\n| `Page Down` | Jump forward 10 images |\n| `Home` | Go to first image |\n| `End` | Go to last image |\n\n## Interface Components\n\n- **Top Controls**: Contrast, brightness, colormap, and action buttons arranged horizontally\n- **Image Display**: Central area with no borders, maximum space utilization\n- **Bottom Navigation**: Image slider and index display\n- **Status Bar**: Min/max values and data type information\n\n## Examples\n\n### Scientific Data Visualization\n\n```python\nimport numpy as np\nfrom image_slide import image_slide\n\n# Simulate time series data\nt = np.linspace(0, 4*np.pi, 50)\nx, y = np.meshgrid(np.linspace(0, 2*np.pi, 100), np.linspace(0, 2*np.pi, 100))\ntime_series = np.array([np.sin(x + t[i]) * np.cos(y + t[i]) for i in range(len(t))])\n\nimage_slide(time_series, \"Time Series Visualization\")\n```\n\n### Medical Imaging\n\n```python\n# Simulate medical image stack (e.g., CT slices)\nslices = np.random.random((30, 256, 256))\n# Add some structure\nfor i, slice_img in enumerate(slices):\n slices[i] = gaussian_filter(slice_img, sigma=2)\n\nimage_slide(slices, \"Medical Image Stack\")\n```\n\n### Fourier Transform Analysis\n\n```python\n# Create test pattern and its FFT\npattern = np.sin(2*np.pi*x*3) * np.cos(2*np.pi*y*2)\nfft_data = np.fft.fftshift(np.fft.fft2(pattern))\n\n# Stack original and FFT for comparison\ncombined = np.array([pattern, np.abs(fft_data), np.angle(fft_data)])\nimage_slide(combined, \"FFT Analysis\")\n```\n\n## Command Line Usage\n\nThe package is designed to be used as a Python library. Import and use the viewer in your Python scripts as shown in the examples above.\n\n## Development\n\n### Setting up Development Environment\n\n```bash\ngit clone https://github.com/GyroTools/image-slide.git\ncd image-slide\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Code Formatting\n\n```bash\nblack image_slide/\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Changelog\n\n### Version 1.0.0\n- Initial release\n- Basic image navigation and display\n- Complex array support\n- Contrast and brightness controls\n- Multiple colormap options\n- Keyboard shortcuts\n- Professional compact interface\n\n## Acknowledgments\n\n- Built with [matplotlib](https://matplotlib.org/) for image display\n- Uses [tkinter](https://docs.python.org/3/library/tkinter.html) for GUI\n- Inspired by scientific image analysis workflows\n\n## Support\n\n- Create an [issue](https://github.com/GyroTools/image-slide/issues) for bug reports\n- Start a [discussion](https://github.com/GyroTools/image-slide/discussions) for questions\n- Check the [documentation](https://github.com/GyroTools/image-slide#readme) for usage examples\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An interactive image viewer for multidimensional numpy arrays",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/GyroTools/image-slide/issues",
"Documentation": "https://github.com/GyroTools/image-slide#readme",
"Homepage": "https://github.com/GyroTools/image-slide",
"Repository": "https://github.com/GyroTools/image-slide"
},
"split_keywords": [
"image",
" viewer",
" numpy",
" matplotlib",
" scientific",
" visualization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f11c768ecb957477e8b47ebe97c0057effb085a289224c6a4fcb1216d94aa4f6",
"md5": "47a621c615e4ab34a78682a8d308cdf2",
"sha256": "938f8b9dd2f2bc000c8511a088c86681fa857cf24d55503ae7a17d55347a449d"
},
"downloads": -1,
"filename": "image_slide-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "47a621c615e4ab34a78682a8d308cdf2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12327,
"upload_time": "2025-10-16T09:29:54",
"upload_time_iso_8601": "2025-10-16T09:29:54.200304Z",
"url": "https://files.pythonhosted.org/packages/f1/1c/768ecb957477e8b47ebe97c0057effb085a289224c6a4fcb1216d94aa4f6/image_slide-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c637377d641d500297056b473fcff592d8d71543a68adbf37c5e2e6d94855bd2",
"md5": "8c5a31890af358c096a919056a3941fa",
"sha256": "a7c893fd14b82874ed8b14d7780478e7a272fb23e8826bb8a74b5850037f24f8"
},
"downloads": -1,
"filename": "image_slide-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "8c5a31890af358c096a919056a3941fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15257,
"upload_time": "2025-10-16T09:29:55",
"upload_time_iso_8601": "2025-10-16T09:29:55.184443Z",
"url": "https://files.pythonhosted.org/packages/c6/37/377d641d500297056b473fcff592d8d71543a68adbf37c5e2e6d94855bd2/image_slide-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-16 09:29:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GyroTools",
"github_project": "image-slide",
"github_not_found": true,
"lcname": "image-slide"
}
JSON
