Camtools

TL;DR

CamTools's documentation website is now available at https://camtools.readthedocs.io/

Summary

Docs: documentation improvements (79, 80, 81, 82, 83, 84)

- Set up Sphinx documentation framework
- Configured Read the Docs hosting (https://camtools.readthedocs.io)
- Added GitHub Actions for documentation builds
- Improved docstrings across codebase

You can build the documentation locally with the following commands:

bash
pip install -e .[docs]
make -C docs clean && make -C docs html
google-chrome docs/_build/html/index.html


Testing: enhanced test coverage (78)

- Added geometry rendering and depth validation tests

Build: relax Open3D and NumPy version requirements (85)

- Relaxed version requirements for Open3D and NumPy dependencies

Summary

Feature/Refactor: Standardized Depth Image and Distance Image Projection (70)
- **Terminology Clarification**: Previously, the terms "depth" (z-depth) and "distance" (Euclidean distance between a 3D point and the camera center) were used interchangeably, leading to confusion. This release clarifies and standardizes the terminology to avoid ambiguity.
- **Function Signatures**: Use `im_depth` or `im_distance` in function signatures to refer to depth images or distance images, respectively.
- **Conversion Functions**: Added conversion functions between distance image and depth image: `ct.convert.im_distance_to_im_depth` and `ct.convert.im_depth_to_im_distance`.

Refactor: Jaxtyping annotation for select functions (66, 68, 69, 70, 76)
- Now, some functions are annotated with e.g., `points: Float[np.ndarray, "n 3"]` to provide better syntax.
- Full type annotation is planned in the future, along with a documentation website.
- Previously we considered adding a flexible backend with `ivy` in this release, but it was canceled for simplicity.

Fix: Use numpy 1.x to Avoid Segfault with Open3D
- **Issue**: A segmentation fault occurs when using certain versions of Open3D with numpy 2.x. This issue is documented in [Open3D issue 6840](https://github.com/isl-org/Open3D/issues/6840).
- **Temporary Fix**: This release restricts the use of numpy 1.x to avoid the segfault. This restriction will likely be removed in future releases when Open3D 0.19 is released, as per [this comment](https://github.com/isl-org/Open3D/issues/6840#issuecomment-2231637165).

API Changes

Added (or renamed as)
- `ct.raycast.mesh_to_im_depth`: new
- `ct.raycast.mesh_to_im_depths`: new
- `ct.raycast.mesh_to_im_distance`: refactored to this
- `ct.raycast.mesh_to_im_distances`: refactored to this
- `ct.convert.im_depth_to_im_distance`: new
- `ct.convert.im_distance_to_im_depth`: new
- `ct.convert.mesh_to_lineset`: new
- `ct.solver.points_to_mesh_distances`: new
- `ct.project.points_to_pixels`: refactored to this
- `ct.project.im_depth_to_point_cloud`: refactored to this

Removed
- `ct.raycast.mesh_to_depth`
- `ct.raycast.mesh_to_depths`
- `ct.project.point_cloud_to_pixel`
- `ct.project.depth_to_point_cloud`

The v0.1.5 release of CamTools brings a host of new features, significant improvements, and various fixes to enhance the overall functionality and usability of the library.

New Features and Improvements

- **Render Geometries to Image**: Introduced the ability to render geometries to an image with custom camera parameters, improving flexibility in rendering (36).
- **Line Radius in Render Geometries**: Enabled `line_radius` support in `ct.render.render_geometries()` for `LineSet`, enhancing the visual representation of lines (38).
- **Efficient Image Cropping**: Enhanced the performance of image cropping, allowing for faster and more efficient operations (39).
- **Depth Image Rendering**: Added `ct.render.render_geometries` for rendering depth images, expanding the rendering capabilities (57).
- **Image Scaling for Depth to Point Cloud**: Added support for image scaling in `ct.project.depth_to_point_cloud()`, allowing for more versatile image processing (54).
- **Single Point Transformation**: Introduced functionality to transform a single point, providing more precise control in point manipulation (60).

Refactoring

- **Consistent Terminology**: Renamed up-down to top-bottom and ensured consistent use of `tblr` throughout the codebase (42).
- **Master to Main Transition**: Updated links and CI configurations to transition from `master` to `main`, aligning with modern repository practices (50).
- **Version Management**: Switched to using `importlib.metadata` for version management for Python 3.8 and above, modernizing the build process (51).
- **Projection API Enhancements**: Improved projection APIs to enhance their functionality and usability (53).
- **Dependency Management**: Removed `torch` dependency, ensuring it is only installed for image metrics, reducing unnecessary dependencies (55).
- **Depth to Point Cloud API Change**: Renamed `return_as_image` to `to_image` in `depth_to_point_cloud`, making the function naming more intuitive (58).
- **Utility Module Renaming**: Renamed `ct.utility` to `ct.util`, streamlining the utility module structure (45).

Fixes

- **Order Preservation in Loops**: Ensured order preservation for `mt_loop` and `mp_loop`, improving consistency in processing (44).
- **PNG Handling in Crop-Borders Tool**: Improved the handling of PNG files with alpha channels in the crop-borders tool (35).
- **OpenCV and OpenGL Conversion**: Fixed issues with transformations and pose conversions between OpenCV and OpenGL (52).
- **Device Assertion Removal**: Removed the assertion for the same device, fixing potential issues related to device handling (56).

Documentation and Build

- **Contribution Section**: Added a new contribution section to the documentation, encouraging community participation and providing guidelines for contributors (40).
- **Strict Editable Mode Installation**: Updated installation instructions to include strict editable mode, ensuring a more reliable setup process (48).

List of Changes
* add built-with-camtools badges in https://github.com/yxlao/camtools/pull/34
* fix: crop-boarders tool handle png with alpha channel in https://github.com/yxlao/camtools/pull/35
* new: render geometries to image with custom camera parameters in https://github.com/yxlao/camtools/pull/36
* new: extract rendering intrinsics (K) and extrinsics (T) set by Open3D in https://github.com/yxlao/camtools/pull/37
* new: support line_radius in ct.render.render_geometries() for LineSet in https://github.com/yxlao/camtools/pull/38
* perf: more efficient ct crop-boarders --same_crop in https://github.com/yxlao/camtools/pull/39
* docs: add contribution section in https://github.com/yxlao/camtools/pull/40
* feat: text renderer, artifact manager, image vstack in https://github.com/yxlao/camtools/pull/41
* refactor: rename up-down to top-bottom, use tblr consistently in https://github.com/yxlao/camtools/pull/42
* perf: faster cropping; parallel imread/crop; mt_loop and mp_loop helper functions in https://github.com/yxlao/camtools/pull/43
* fix: preserve order for mt_loop and mp_loop in https://github.com/yxlao/camtools/pull/44
* refactor: ct.utility->ct.util in https://github.com/yxlao/camtools/pull/45
* ci: disable concurrency in https://github.com/yxlao/camtools/pull/46
* docs: install with strict editable mode in https://github.com/yxlao/camtools/pull/48
* refactor: rename create_camera_frames to create_camera_frustums in https://github.com/yxlao/camtools/pull/49
* refactor: master->main for links and ci in https://github.com/yxlao/camtools/pull/50
* build: use importlib.metadata to get version for py>=3.8 in https://github.com/yxlao/camtools/pull/51
* fix: opencv<->opengl T and pose convert in https://github.com/yxlao/camtools/pull/52
* refactor: improved projection APIs in https://github.com/yxlao/camtools/pull/53
* new: support image scaling for ct.project.depth_to_point_cloud() in https://github.com/yxlao/camtools/pull/54
* refactor: remove torch dependency, only install torch for image metrics in https://github.com/yxlao/camtools/pull/55
* fix: remove assert same device in https://github.com/yxlao/camtools/pull/56
* new: ct.render.render_geometries as depth image in https://github.com/yxlao/camtools/pull/57
* refactor: return_as_image->to_image for depth_to_point_cloud in https://github.com/yxlao/camtools/pull/58
* new: transform a single point in https://github.com/yxlao/camtools/pull/60
* build: python version support update to 3.8 - 3.11 in https://github.com/yxlao/camtools/pull/63
* build: v0.1.5 version bump in https://github.com/yxlao/camtools/pull/65

**Full Changelog**: https://github.com/yxlao/camtools/compare/v0.1.4...v0.1.5

---
For more details, visit the [CamTools GitHub repository](https://github.com/yxlao/camtools). Your feedback and contributions are welcome.

The v0.1.4 release of CamTools introduces a range of new features, improvements, and fixes.

New Features and Improvements

- **Up Triangle, Point-Plane Distance, Exact Camera Size**: Introduced new camera frame functionalities including up triangle and point-plane distance calculation (19).
- **Camera Pose from Spherical Coordinate System**: Added camera pose determination using spherical coordinates (20).
- **Command Line Tool for Image Compression**: Added new command-line tool for efficient PNG and JPG image compression (25).
- **Improved Readme Graphics**: Enhanced readme graphics for better visual appeal and information clarity (30).
- **CamTools Logo**: Introduced a new visual identity with the CamTools logo (29).

Refactoring

- **Camera Frame Creation APIs**: Refactored camera frame creation APIs to improve clarity and usability (22).
- **Project to Transform**: Renamed `ct.project.homo_project` to `ct.transform.transform_points` for better functional alignment (23).
- **Normalization and Plot Module Changes**: Moved functionalities from `ct.stat` to `ct.normalize` and removed `ct.plot` module (24).

Fixes

- **Handling Alpha PNGs and Avoiding Duplicated Compression**: Improved handling of PNGs with alpha channels and optimized image compression process (26).
- **Continuous Integration and Tests**: Addressed issues in CI and tests to ensure library stability and reliability (28).

Automation

- **Automatic PyPI Release Script**: Streamlined PyPI release process with an automated script (18).

---

For more details, visit the [CamTools GitHub repository](https://github.com/yxlao/camtools). Your feedback and contributions are welcome.

The camtools v0.1.3 release features important bug fixes and API changes.

- Fix: Mesh ray cast depth calculation (11)
- Fix: Normalize by `K[2, 2]` when decomposing `P` (15)
- Refactor: Renamed blender->opengl, pinhole->opencv
python
ct.convert.T_opencv_to_opengl()
ct.convert.T_opengl_to_opencv()
ct.convert.pose_opencv_to_opengl()
ct.convert.pose_opengl_to_opencv()

- Fix `ct` command line tool module import issue
- Add unit test CI and PyPI CI