update README.md with detailed project description, features, installation instructions, and performance benchmarks
This commit is contained in:
ImBenji
215
README.md
215
README.md
@@ -1,16 +1,213 @@
|
|||||||
# binary_viewer
|
# Binary Viewer
|
||||||
|
|
||||||
A new Flutter project.
|
A cross-platform Flutter application for viewing and analyzing binary files with multiple data interpretation modes and advanced scrolling capabilities.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## 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
|
## Getting Started
|
||||||
|
|
||||||
This project is a starting point for a Flutter application.
|
### Prerequisites
|
||||||
|
- Flutter SDK (>=3.9.0-100.2.beta)
|
||||||
|
- Dart SDK
|
||||||
|
- Platform-specific development tools (for building native apps)
|
||||||
|
|
||||||
A few resources to get you started if this is your first Flutter project:
|
### Installation
|
||||||
|
|
||||||
- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
|
1. **Clone the repository**
|
||||||
- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
|
```bash
|
||||||
|
git clone <repository-url>
|
||||||
|
cd binary_viewer
|
||||||
|
```
|
||||||
|
|
||||||
For help getting started with Flutter development, view the
|
2. **Install dependencies**
|
||||||
[online documentation](https://docs.flutter.dev/), which offers tutorials,
|
```bash
|
||||||
samples, guidance on mobile development, and a full API reference.
|
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.
|
||||||
Reference in New Issue
Block a user