From 638c9a39613b5e4edd5fff253a2697c818c175b4 Mon Sep 17 00:00:00 2001 From: ImBenji Date: Thu, 4 Sep 2025 04:24:18 +0100 Subject: [PATCH] update README.md with detailed project description, features, installation instructions, and performance benchmarks --- README.md | 215 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 206 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 94f85e1..8aeb1c9 100644 --- a/README.md +++ b/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. + +![Binary Viewer Screenshot](assets/screenshot.png) + +## 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 -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) -- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook) +1. **Clone the repository** + ```bash + git clone + cd binary_viewer + ``` -For help getting started with Flutter development, view the -[online documentation](https://docs.flutter.dev/), which offers tutorials, -samples, guidance on mobile development, and a full API reference. +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. \ No newline at end of file