improved performance across all operations

[bghira]

This pull request significantly revises the documentation for the project, focusing on clarifying the performance claims, updating usage instructions, and providing more accurate and transparent benchmarking and API information. The tone has been shifted from marketing-driven to a more technical and realistic description of the project's strengths and limitations. The most important changes are grouped below.

Documentation and Messaging Overhaul:

• The README and BENCHMARKS documentation have been rewritten to remove aggressive marketing language and instead provide a clear, technical overview of what the library does, its intended use cases, and realistic performance expectations. It now emphasizes that TrainingSample is not a universal replacement for OpenCV, and that performance depends on workload, image size, and other system factors. [1] [2]

Benchmarking and Performance Reporting:

• The benchmarks section now describes how to run benchmarks, what scenarios are measured, and how to interpret results. It provides concrete, recent benchmark numbers with context and explains the impact of recent optimizations (such as zero-copy ndarray→NumPy transfer and channel-sum fast path for luminance). [1] [2]
• Guidance is given on using the benchmarks to detect regressions, with practical questions for developers to consider. There is also a new section outlining plans for future benchmark improvements.

API Reference and Example Improvements:

• The API reference has been rewritten for clarity, with updated signatures, parameter types, and behavioral notes for each function, both in Python and Rust. Examples have been updated to match the new documentation style and to illustrate typical usage more clearly.
• Example code in the README now uses realistic batch processing scenarios and highlights the available OpenCV-compatible helper functions.

Technical Details and Build Instructions:

• The documentation now includes explicit instructions for building from source, including how to unset problematic environment variables for OpenCV/LLVM detection, and points to further resources for static OpenCV builds. [1] [2]
• Details about the hybrid architecture, implementation choices for each operation type, and supported features are included, giving users a better understanding of when and why to use each function.

Quality and Regression Checks:

• There is now a dedicated section describing how quality is validated (shape, value accuracy, tolerance to non-contiguous arrays, etc.) and what signals to watch for when investigating regressions.

These changes make the documentation more accurate, developer-friendly, and maintainable, and set realistic expectations for users and contributors.