update README.md with detailed project description, features, installation instructions, and performance benchmarks

2025-09-04 04:24:18 +01:00
parent fede06835a
commit 638c9a3961
1 changed files with 206 additions and 9 deletions
--- 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 <repository-url>
+   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.