226 lines
9.5 KiB
Markdown
226 lines
9.5 KiB
Markdown
# Binary Viewer
|
|
|
|
A cross-platform Flutter application for viewing and analyzing binary files with multiple data interpretation modes and advanced scrolling capabilities.
|
|
|
|
|
|
## 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. |