# Binary Viewer

A cross-platform Flutter application for viewing and analyzing binary files with multiple data interpretation modes and advanced scrolling capabilities.

![Binary Viewer Screenshot](image.png)
## Why This Exists

I couldn't find any good binary viewers for macOS that looked as nice as the ones I was used to on Windows (like this [Binary Viewer](https://binary-viewer.en.softonic.com/)). The macOS options all seemed lacking in terms of modern UI and good user experience.

Most existing options were either:
- Command-line only (`xxd`, `hexdump`) - functional but not great for interactive analysis
- Ancient GUI applications with outdated interfaces
- Heavy-weight development tools that were overkill for simple binary viewing
- Cross-platform Java applications that felt foreign on macOS

I wanted something that felt native, looked modern, and provided the dual-pane analysis capabilities I was used to on Windows. Rather than compromise or constantly switch platforms for binary analysis work, I decided to build exactly what I wanted - a clean, fast, feature-rich binary viewer that works beautifully on macOS and can be easily shared across platforms.

This project represents the binary viewer I wish existed when I started looking for one.

## Features

### Core Functionality
- **File Selection**: Browse and open any binary file using the native file picker
- **Multi-View Interface**: Dual-pane view allowing different data interpretations simultaneously
- **Real-time File Reading**: Efficient isolate-based file reading with caching and throttling
- **Cross-Platform**: Supports Windows, macOS, Linux, iOS, Android, and Web

### Data View Modes
- **Hexadecimal**: Traditional hex view with byte-by-byte representation
- **ASCII**: Text representation of printable characters
- **Binary**: Raw binary representation (0s and 1s)
- **Integer**: 32-bit signed integer interpretation
- **Float**: 32-bit floating-point interpretation  
- **Double**: 64-bit floating-point interpretation

### Endianness Support
- **Little Endian**: Intel/AMD standard byte ordering
- **Big Endian**: Network/SPARC standard byte ordering
- Independent endianness selection for each view pane

### Advanced UI Features
- **Dual-Pane Layout**: Left and right views can display different data interpretations simultaneously
- **Interactive Address Navigation**: Click on any byte to see its absolute address
- **Custom Scrollbars**: Enhanced scrollbar implementation with asymmetric margin support
- **Synchronized Horizontal Scrolling**: Both header and content scroll together
- **Theming Support**: 12 built-in color themes (Light/Dark variants of Default, Blue, Green, Orange, Violet, Rose)
- **Responsive Design**: Adapts to different window sizes and orientations

### Performance Optimizations
- **Virtual Scrolling**: Only renders visible rows for optimal performance with large files
- **Isolate-Based File I/O**: Non-blocking file operations using Dart isolates
- **Intelligent Caching**: Row-based caching with automatic cleanup
- **Throttled Reading**: Configurable read throttling to prevent UI freezing (40 reads/second)
- **Debounced Updates**: Smooth scrolling with optimized update frequency

## Technical Architecture

### Core Components
- **Main Application** (`lib/main.dart`): Primary UI and business logic
- **Custom Scrollbar** (`lib/widgets/scrollview.dart`): Enhanced RawScrollbar with asymmetric margin support
- **Theme System**: Dynamic theme switching with persistent preferences
- **File Reader Isolate**: Background file processing for non-blocking I/O

### Key Technical Features
- **Asymmetric Scrollbar Margins**: Custom EdgeInsets support instead of Flutter's symmetric constraints
- **Force Interactive Scrollbars**: Override default interactivity rules for better UX
- **Dual ScrollController System**: Independent vertical and horizontal scroll management
- **Memory-Efficient Row Building**: On-demand row construction with viewport-based optimization

## Getting Started

### Prerequisites
- Flutter SDK (>=3.9.0-100.2.beta)
- Dart SDK
- Platform-specific development tools (for building native apps)

### Installation

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd binary_viewer
   ```

2. **Install dependencies**
   ```bash
   flutter pub get
   ```

3. **Run the application**
   ```bash
   flutter run
   ```

### Building for Production

#### Desktop (Recommended)
```bash
flutter build macos   # Tested platform
flutter build windows # Untested but should work
flutter build linux   # Untested but should work
```

#### Web
```bash
flutter build web
```

#### Mobile (Not Recommended)
While technically possible to build for mobile, the UI is not optimized for touch interfaces:
```bash
flutter build ios  # Poor UX - not recommended
flutter build apk  # Poor UX - not recommended  
```

**Note**: This application is designed for desktop use with keyboard and mouse interaction. Mobile builds will have usability issues due to small touch targets and complex multi-pane layouts.

## Usage

### Basic Operations
1. **Open a File**: Use File → Open to select any binary file
2. **Select View Mode**: Choose interpretation mode from the dropdown (hex, ASCII, binary, etc.)
3. **Choose Endianness**: Select byte order interpretation (little/big endian)
4. **Navigate**: Scroll through the file or click on addresses for navigation
5. **Switch Themes**: Use Options → Theme to change the color scheme

### View Modes Explained

- **Hex View**: Shows each byte as a two-digit hexadecimal number (00-FF)
- **ASCII View**: Displays printable characters (32-126) or dots for non-printable bytes
- **Binary View**: Shows each byte as 8 binary digits (00000000-11111111)
- **Integer View**: Interprets 4-byte chunks as signed 32-bit integers
- **Float View**: Interprets 4-byte chunks as IEEE 754 single-precision floats
- **Double View**: Interprets 8-byte chunks as IEEE 754 double-precision floats

### Advanced Features

#### Address Navigation
- Click on any data element to see its absolute file address
- Addresses are displayed in hexadecimal format with 0x prefix
- Selected bytes are highlighted with a glowing border effect

#### Dual-Pane Analysis
- Left and right panes can show the same data in different formats
- Example: View hex on the left and ASCII interpretation on the right
- Independent endianness settings for each pane

#### Performance Tuning
The application automatically optimizes performance but you can adjust:
- `maxReadsPerSecond`: File read throttling (default: 40/sec)
- `bufferRows`: Viewport buffer size (default: 10 rows)
- Cache cleanup frequency based on scroll distance

## Dependencies

### Core Dependencies
- **flutter**: Framework
- **file_picker**: Native file selection dialogs
- **shadcn_flutter**: Modern UI components
- **shared_preferences**: Theme persistence
- **provider**: State management
- **google_fonts**: Typography

### Development Dependencies
- **flutter_test**: Testing framework
- **flutter_lints**: Code quality linting

## Architecture Details

### Performance Considerations
The application is designed to handle large binary files efficiently:

- **Lazy Loading**: Only loads visible data chunks
- **Memory Management**: Automatic cache cleanup based on scroll distance
- **Non-blocking I/O**: File operations run in background isolates
- **Viewport-based Rendering**: Only renders visible rows plus buffer

### Custom Scrollbar Implementation
The custom scrollbar widget extends Flutter's RawScrollbar with:

- **EdgeInsets Support**: Asymmetric margins (left≠right, top≠bottom)
- **Force Interactive**: Override default interactivity constraints
- **Render Offset**: Additional positioning control independent of margins
- **Synchronized Scrolling**: Coordinated horizontal and vertical scrollbars

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin feature-name`
5. Submit a pull request

### Code Style
- Follow Flutter/Dart conventions
- Use meaningful variable names
- Comment complex algorithms
- Maintain performance considerations for large file handling

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Platform Support

| Platform | Status | Notes |
|----------|--------|-------|
| macOS    | ✅ Tested | Fully tested, native file dialogs, optimal experience |
| Windows  | ⚠️ Untested | Should work, native file dialogs expected |
| Linux    | ⚠️ Untested | Should work, native file dialogs expected |
| Web      | ⚠️ Untested | Should work but with performance limitations |
| iOS      | ❌ Not Recommended | UI not optimized for mobile, poor UX expected |
| Android  | ❌ Not Recommended | UI not optimized for mobile, poor UX expected |

**Note**: This application has only been tested on macOS, but there's no technical reason it shouldn't work on other desktop platforms. The UI is designed for desktop/laptop screens with mouse interaction and would provide a poor user experience on mobile devices due to small touch targets and complex multi-pane layout.

## Performance Benchmarks

The application has been tested with files up to several GB in size:

- **Small files** (<1MB): Instant loading and scrolling
- **Medium files** (1MB-100MB): Smooth performance with minor loading delays
- **Large files** (100MB-1GB): Good performance with optimized memory usage
- **Very large files** (>1GB): Functional with slower initial loading

Memory usage scales with viewport size rather than file size due to the virtual scrolling implementation.