Add query_intersections() method for efficient AABB pair detection (#47)

* Add query_intersections() method for efficient AABB pair detection

Implements a new query_intersections() method that efficiently finds all
pairs of intersecting bounding boxes in the tree, addressing the feature
request in issue #46.

Key features:
- Returns numpy array of shape (n_pairs, 2) with index pairs (i, j) where i < j
- Parallel processing using std::thread for improved performance
- Automatic double-precision refinement when exact coordinates are available
- No duplicate pairs or self-pairs
- Similar to scipy.spatial.cKDTree.query_pairs but for AABBs

This eliminates the need for manual post-processing of batch_query results
using np.vectorize, np.repeat, and np.concatenate, which previously
canceled out the performance gains from C++ parallelization.

Changes:
- cpp/prtree.h: Added query_intersections() method to PRTree class
- cpp/main.cc: Added Python bindings for all dimensions (2D, 3D, 4D)
- tests/test_PRTree.py: Added comprehensive tests including edge cases
- README.md: Updated documentation with usage examples

All tests pass (45 new tests + existing tests).

Resolves #46

* Add comprehensive Makefile and development documentation

Adds a complete development workflow automation through Make commands,
making it easier for developers to build, test, and contribute to the project.

Key additions:
- Makefile: Comprehensive build automation with 30+ commands
  - Build: build, build-release, rebuild, debug-build
  - Test: test, test-verbose, test-fast, test-coverage, test-one
  - Packaging: wheel, sdist, release
  - Maintenance: clean, clean-all, format, lint
  - Development: init, dev, install-deps, check

- CONTRIBUTING.md: Complete developer guide
  - Development setup instructions
  - Workflow documentation
  - Coding standards
  - Troubleshooting guide

- Enhanced .gitignore: Additional patterns for build artifacts,
  coverage reports, and temporary files

All content is in English and designed to be generic and reusable
for any feature development, not specific to any particular functionality.

Benefits:
- Streamlined development workflow
- Consistent build and test procedures
- Easy onboarding for new contributors
- CI-compatible check commands

* Add Makefile usage reference guide

* Format C++ code with clang-format

Apply clang-format to all C++ source files for consistent code style.
This is an automatic formatting change with no functional modifications.

Files affected:
- cpp/main.cc: Brace positioning and line wrapping
- cpp/parallel.h: Formatting improvements
- cpp/prtree.h: Consistent formatting throughout
- cpp/small_vector.h: Style consistency updates

These changes were generated by running 'make format'.

* Fix: Guard against zero hardware_concurrency in query_intersections

When std::thread::hardware_concurrency() returns 0 (which is permitted
when the runtime cannot detect the CPU count), n_threads was set to zero.
This caused undefined behavior:
- In single-threaded path: writes to thread_pairs[0] on empty vector
- In parallel path: loops never execute, returning no intersections

Apply the same guard used in find_all() to ensure at least one thread.

This fixes a critical bug that could cause crashes or incorrect results
on systems where hardware_concurrency() returns 0.

Fixes: P1 Badge Guard against zero hardware_concurrency
Reported-by: User feedback

---------

Co-authored-by: Claude <[email protected]>

Author: atksh

.gitignore

@@ -7,6 +7,7 @@ _build/
 _generate/
 *.so
 *.so.*
+*.a
 *.py[cod]
 *.egg-info
 .eggs/
@@ -17,4 +18,26 @@ __pycache__/
 .ipynb_checkpoints/
 .vscode/
 .DS_Store
-*.prof
+*.prof
+
+# Test coverage
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+
+# Pytest
+.pytest_cache/
+.pytest_cache
+
+# Build artifacts
+*.o
+*.obj
+*.lib
+*.exp
+
+# Temporary files
+*.tmp
+*.bak
+*~

CONTRIBUTING.md

@@ -0,0 +1,312 @@
+# Contributing Guide
+
+Thank you for your interest in contributing to python_prtree!
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.8 or higher
+- CMake 3.12 or higher
+- C++17-compatible compiler (GCC 7+, Clang 5+, MSVC 2017+)
+- Git
+
+### Quick Start
+
+```bash
+# Clone the repository
+git clone --recursive https://github.com/atksh/python_prtree
+cd python_prtree
+
+# Setup development environment (first time only)
+make dev
+
+# Build and test
+make build
+make test
+```
+
+## Makefile Commands
+
+We provide a Makefile to streamline the development workflow.
+
+### Show Help
+
+```bash
+make help
+```
+
+### Initial Setup
+
+```bash
+make init              # Initialize submodules + check dependencies
+make install-deps      # Install development dependencies
+make dev              # Run init + install-deps + build at once
+```
+
+### Building
+
+```bash
+make build            # Build in debug mode
+make build-release    # Build in release mode
+make rebuild          # Clean build (clean + build)
+make debug-build      # Build with debug symbols
+```
+
+### Testing
+
+```bash
+make test                    # Run all tests
+make test-verbose            # Run tests in verbose mode
+make test-fast               # Run tests in parallel (faster)
+make test-coverage           # Run tests with coverage
+make test-one TEST=<name>    # Run specific test(s)
+```
+
+### Cleanup
+
+```bash
+make clean      # Remove build artifacts
+make clean-all  # Remove everything including submodules
+```
+
+### Packaging
+
+```bash
+make wheel     # Build wheel package
+make sdist     # Build source distribution
+make release   # Build release packages (wheel + sdist)
+```
+
+### Other Commands
+
+```bash
+make format      # Format C++ code (requires clang-format)
+make lint        # Lint code
+make info        # Show project information
+make check       # Run build and tests (for CI)
+make quick       # Quick test (clean + build + test)
+```
+
+## Development Workflow
+
+### Adding New Features
+
+1. **Create a branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Setup development environment (first time only)**
+   ```bash
+   make dev
+   ```
+
+3. **Make changes**
+   - C++ code: `cpp/prtree.h`, `cpp/main.cc`
+   - Python wrapper: `src/python_prtree/__init__.py`
+   - Tests: `tests/test_PRTree.py`
+
+4. **Build and test**
+   ```bash
+   make rebuild
+   make test
+   ```
+
+5. **Check code quality**
+   ```bash
+   make format  # Format code
+   make lint    # Lint code
+   ```
+
+6. **Commit**
+   ```bash
+   git add -A
+   git commit -m "Add: description of new feature"
+   ```
+
+7. **Create pull request**
+
+### Test-Driven Development (TDD)
+
+1. **Write tests first**
+   ```python
+   # tests/test_PRTree.py
+   def test_new_feature():
+       # Write test code
+       pass
+   ```
+
+2. **Verify test fails**
+   ```bash
+   make test-one TEST=test_new_feature
+   ```
+
+3. **Implement feature**
+   ```cpp
+   // cpp/prtree.h
+   // Add implementation
+   ```
+
+4. **Build and test**
+   ```bash
+   make build
+   make test-one TEST=test_new_feature
+   ```
+
+5. **Run all tests**
+   ```bash
+   make test
+   ```
+
+### Debugging
+
+Build with debug symbols for debugging:
+
+```bash
+make debug-build
+gdb python3
+(gdb) run -c "from python_prtree import PRTree2D; ..."
+```
+
+### Checking Coverage
+
+```bash
+make test-coverage
+# Open htmlcov/index.html in browser
+```
+
+## Coding Standards
+
+### C++
+
+- **Style**: Follow Google C++ Style Guide
+- **Formatting**: Use clang-format (`make format`)
+- **Naming conventions**:
+  - Classes: `PascalCase` (e.g., `PRTree`)
+  - Functions/methods: `snake_case` (e.g., `batch_query`)
+  - Variables: `snake_case`
+  - Constants: `UPPER_CASE`
+
+### Python
+
+- **Style**: Follow PEP 8
+- **Line length**: Maximum 100 characters
+- **Documentation**: Use docstrings
+
+### Tests
+
+- Add tests for all new features
+- Test case naming: `test_<feature>_<case>`
+- Cover edge cases
+- Use parameterized tests (`@pytest.mark.parametrize`)
+
+## Project Structure
+
+```
+python_prtree/
+├── cpp/                    # C++ implementation
+│   ├── prtree.h           # PRTree core implementation
+│   ├── main.cc            # Python bindings
+│   ├── parallel.h         # Parallel processing utilities
+│   └── small_vector.h     # Optimized vector
+├── src/python_prtree/     # Python wrapper
+│   └── __init__.py
+├── tests/                 # Test suite
+│   └── test_PRTree.py
+├── third/                 # Third-party libraries (submodules)
+│   ├── pybind11/
+│   └── snappy/
+├── CMakeLists.txt         # CMake configuration
+├── setup.py               # Packaging configuration
+├── Makefile              # Development workflow
+└── README.md             # User documentation
+```
+
+## Troubleshooting
+
+### Submodules Not Found
+
+```bash
+make clean-all
+make init
+```
+
+### Build Errors
+
+```bash
+make clean
+make build
+```
+
+### Test Failures
+
+1. Verify build succeeded
+   ```bash
+   make build
+   ```
+
+2. Check environment variables
+   ```bash
+   echo $PYTHONPATH  # Should include src directory
+   ```
+
+3. Run in verbose mode
+   ```bash
+   make test-verbose
+   ```
+
+### CMake Errors
+
+Clear CMake cache:
+```bash
+rm -rf build
+make build
+```
+
+## Continuous Integration (CI)
+
+When you create a pull request, the following checks run automatically:
+
+- Build verification
+- All tests
+- Code coverage
+
+Run the same checks locally:
+```bash
+make check
+```
+
+## Release Process
+
+1. **Update version**
+   - Update version number in `setup.py`
+
+2. **Update changelog**
+   - Update "New Features and Changes" section in `README.md`
+
+3. **Run tests**
+   ```bash
+   make clean
+   make check
+   ```
+
+4. **Build release packages**
+   ```bash
+   make release
+   ```
+
+5. **Create tag**
+   ```bash
+   git tag -a v0.x.x -m "Release v0.x.x"
+   git push origin v0.x.x
+   ```
+
+## Questions and Support
+
+- **Issues**: https://github.com/atksh/python_prtree/issues
+- **Discussions**: https://github.com/atksh/python_prtree/discussions
+
+## License
+
+Contributions to this project will be released under the same license as the project (MIT).