initial commit

Author: ruelalarcon

LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ruel Nathaniel Alarcon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,192 @@
+# cpf3d
+
+> A python library to read and edit [3cpf](https://github.com/ruelalarcon/3cpf) files. Requires
+> python 3.8.
+
+**Features**
+
+- Read 3cpf files into easily usable data
+- Create new points and frames
+- Apply basic position, scale, and rotation transformations to all points in a 3cpf file
+- Write 3cpf data into 3cpf files
+
+## Installation
+
+The package can be installed with `pip`.
+
+```bash
+pip install cpf3d
+```
+
+## Usage
+
+### Reading files
+
+The `cpf3d.load` function can be used to load a 3cpf files as a `cpf3d.PointFrames` object, which has points and frames.
+
+```python
+import cpf3d
+
+# Load a 3cpf file
+pf = cpf3d.load('miku_example.3cpf')
+
+# From here, we can access any necessary data
+print('# of Points:', len(pf.points))
+print('# of Frames:', len(pf.frames))
+
+# Point colors
+print('\nColors of First 5 Points:')
+for point in pf.points[:5]:
+    print(point.color)
+
+# Position of specific point at specific frame
+print('\nPositions of Point 0 Throughout First 5 Frames:')
+for i in range(5):
+    print(pf.get_position(0, i))
+```
+Output:
+```
+# of Points: 600
+# of Frames: 60
+
+Colors of First 5 Points:
+(112, 112, 112)
+(112, 112, 112)
+(0, 0, 0)
+(112, 112, 112)
+(112, 112, 112)
+
+Positions of Point 0 Throughout First 5 Frames:
+[-0.01653824  0.05377164  1.10009   ]
+[-0.01205087  0.05788074  1.0995283 ]
+[-0.00502312  0.06201064  1.1008564 ]
+[0.00529542 0.06594937 1.1022888 ]
+[0.01859665 0.06944766 1.1035271 ]
+```
+
+If your use-case uses a different coordinate order (XYZ vs. YXZ for example), you can load a 3cpf with any coordinate order of your choice.
+```python
+import cpf3d
+
+# Load a 3cpf file, with dimensions in the order of xzy, rather than the default xyz
+pf = cpf3d.load('miku_example.3cpf', 'xzy')
+```
+
+### Editing and Creating 3cpf Files
+
+You can edit instances of `cpf3d.PointFrames` and save them as 3cpf files.
+
+```python
+import cpf3d
+
+# Editing an existing 3cpf file
+pf = nbtlib.load('miku_example.3cpf')
+
+# Rotate entire animation 90 degrees along the Z-axis
+# Scale to half size across all dimensions
+# And move 1 along the X-axis
+pf.apply_rotation(0, 0, 90) \
+  .apply_scale(.5, .5, .5) \
+  .apply_offset(1, 0, 0)
+
+# Save the now-transformed point frames into a new file
+pf.save('miku_example_transformed.3cpf')
+```
+
+Or write a 3cpf file from scratch.
+```python
+import cpf3d
+from cpf3d import PointFrames, Point, Frame
+
+# Creating a 3cpf file from scratch
+custom_pf = PointFrames()
+
+point_r = Point(255, 0, 0) # Red point
+point_g = Point(0, 255, 0) # Green point
+
+custom_pf.add_point(point_r)
+custom_pf.add_point(point_g)
+
+# First frame: Red point at 1,1,1. Green point at 2,2,2
+frame_1 = Frame([[1.0, 1.0, 1.0], [2.0, 2.0, 2.0]])
+
+# Second frame: Red point at 2,2,2. Green point at 4,4,4
+frame_2 = Frame([[2.0, 2.0, 2.0], [4.0, 4.0, 4.0]])
+custom_pf.add_frame(frame_1)
+custom_pf.add_frame(frame_2)
+
+# Scale it all by ten times
+custom_pf.apply_scale(10, 10, 10)
+
+# Export to a 3cpf file
+custom_pf.save('my_pointframes.3cpf')
+```
+
+### Adding Points or Frames to Existing 3cpf Data
+
+There are a variety of restrictions related to adding points or frames to existing 3cpf animations.
+
+**Firstly,** you cannot add frames *before* adding any points.
+```python
+pf = PointFrames()
+
+# Will cause an error, as there are no points to attach this positional data to
+frame = Frame([[1.0, 2.0, 3.0]])
+```
+
+**Secondly,** when adding new frames, you must have one positional entry for each point.
+```python
+# Assume this 3cpf file contains 2 points
+pf = cpf3d.load('2points.3cpf')
+
+# Will cause an error, as we are adding a frame with 1 position, but there are 2 points
+frame = Frame([[1.0, 2.0, 3.0]])
+pf.add_frame(frame)
+
+# Similarly, this would also error
+frame = Frame([[1.0, 2.0, 3.0], [1.0, 2.0, 3.0], [1.0, 2.0, 3.0]])
+pf.add_frame(frame)
+```
+
+**Lastly,** when adding new points, if you already have frames in your 3cpf file, you must provide positions for your new point at each frame.
+
+```python
+# Assume this 3cpf file contains 2 points and 2 frames
+pf = cpf3d.load('2points2frames.3cpf')
+
+# Will cause an error, as there are already frames in this 3cpf animation
+point = Point(255, 255, 255)
+pf.add_point(point)
+```
+
+We would instead need to do something like this:
+```python
+pf = cpf3d.load('2points2frames.3cpf')
+
+point = Point(255, 255, 255)
+
+# This point moves from 1,1,1 to 2,2,2 through frames 0 and 1
+positions = [[1.0, 1.0, 1.0], [2.0, 2.0, 2.0]]
+
+pf.add_frame(point, positions) # This works fine
+```
+
+This is necessary due to the nature of 3cpf files, in that each point must have corresponding positional data within each frame chunk.
+
+## Contributing
+
+Contributions are welcome. This project is packaged with python's built-in [setuptools](https://setuptools.pypa.io/en/latest/).
+
+To install this package locally for development, you can clone or download this repository and navigate to it in your terminal.
+
+You should now be able to install it locally, including development dependencies.
+
+```bash
+pip install -e .[dev]
+```
+
+You can run the tests by simply executing pytest from the top directory.
+
+```bash
+pytest
+```

cpf3d/__init__.py

@@ -0,0 +1,3 @@
+from .frame import Frame
+from .point import Point
+from .point_frames import PointFrames, load

cpf3d/frame.py

@@ -0,0 +1,15 @@
+from typing import List, Tuple, Union
+
+import numpy as np
+
+
+class Frame:
+	def __init__(self, positions: Union[np.ndarray, List[Tuple[float, float, float]]]):
+		self.positions = np.array(positions)
+
+	def __str__(self):
+		return f'Frame(#positions={len(self.positions)})'
+
+	def __repr__(self):
+		with np.printoptions(threshold=np.inf):
+			return f'Frame(positions={self.positions})'

cpf3d/point.py

@@ -0,0 +1,9 @@
+class Point:
+	def __init__(self, r: int, g: int, b: int):
+		self.color = (r, g, b)
+
+	def __str__(self):
+		return f'Point(color={self.color})'
+
+	def __repr__(self):
+		return f'Point(color={self.color})'

cpf3d/point_frames.py

@@ -0,0 +1,147 @@
+import struct
+from typing import List, Tuple, Union
+from zlib import crc32
+
+import numpy as np
+
+from .frame import Frame
+from .point import Point
+
+
+class PointFrames:
+	def __init__(self):
+		self.points = []
+		self.frames = []
+
+	def add_point(self, point: Point, positions: Union[np.ndarray, List[Tuple[float, float, float]]] = None):
+		if len(self.frames) != 0 and (positions is None or len(positions) != len(self.frames)):
+			raise ValueError('When adding a new point to a PointFrame that already has frames, you must provide a positions array for its position at each frame')
+		self.points.append(point)
+
+		if positions is None:
+			return
+
+		for frame, position in zip(self.frames, positions):
+			frame.positions = np.append(frame.positions, [position], axis=0)
+
+	def add_frame(self, frame: Frame):
+		if len(self.points) == 0:
+			raise ValueError('Cannot add frames to a PointFrame with no points')
+
+		if len(frame.positions) != len(self.points):
+			raise ValueError('Frame must contain 1 position for each existing point')
+		self.frames.append(frame)
+
+	def get_position(self, point_index: int, frame_index: int) -> Tuple[float, float, float]:
+		return self.frames[frame_index].positions[point_index]
+
+	def get_positions(self, frame_index: int) -> np.ndarray:
+		return self.frames[frame_index].positions
+
+	def apply_offset(self, ax1: float, ax2: float, ax3: float):
+		offset = (ax1, ax2, ax3)
+		for frame in self.frames:
+			frame.positions += np.array(offset)
+
+		return self
+
+	def apply_rotation(self, deg1: float, deg2: float, deg3: float):
+		degrees = np.radians((deg1, deg2, deg3))
+
+		ax1 = np.array([[1, 0, 0],
+					   [0, np.cos(degrees[0]), -np.sin(degrees[0])],
+					   [0, np.sin(degrees[0]), np.cos(degrees[0])]])
+
+		ax2 = np.array([[np.cos(degrees[1]), 0, np.sin(degrees[1])],
+					   [0, 1, 0],
+					   [-np.sin(degrees[1]), 0, np.cos(degrees[1])]])
+
+		ax3 = np.array([[np.cos(degrees[2]), -np.sin(degrees[2]), 0],
+					   [np.sin(degrees[2]), np.cos(degrees[2]), 0],
+					   [0, 0, 1]])
+
+		rotation_matrix = np.dot(ax3, np.dot(ax2, ax1))
+
+		for frame in self.frames:
+			frame.positions = np.dot(frame.positions, rotation_matrix.T)
+
+		return self
+
+	def apply_scale(self, ax1: float, ax2: float, ax3: float):
+		scale = (ax1, ax2, ax3)
+		for frame in self.frames:
+			frame.positions *= np.array(scale)
+
+		return self
+
+	def save(self, file_path: str):
+		with open(file_path, 'wb') as file:
+			version = 1
+
+			file.write(b'3CPF')
+			file.write(struct.pack('I', version))
+			checksum_offset = file.tell()
+			file.write(b'\x00\x00\x00\x00')
+			file.write(struct.pack('I', len(self.points)))
+			file.write(struct.pack('I', len(self.frames)))
+
+			point_color_data = bytearray()
+			frame_position_data = bytearray()
+
+			for point in self.points:
+				point_color_data += struct.pack('3B', *point.color)
+
+			for frame in self.frames:
+				for position in frame.positions:
+					frame_position_data += struct.pack('3f', *position)
+
+			file.write(point_color_data)
+			file.write(frame_position_data)
+
+			checksum = crc32(point_color_data + frame_position_data) & 0xffffffff
+
+		with open(file_path, 'r+b') as file:
+			file.seek(checksum_offset)
+			file.write(struct.pack('I', checksum))
+
+	def __str__(self):
+		return f'PointFrames(#points={len(self.points)}, #frames={len(self.frames)})'
+
+	def __repr__(self):
+		return f'PointFrames(points={repr(self.points)}, frames={repr(self.frames)})'
+
+def load(file_path: str, coordinate_order: str = 'xyz') -> PointFrames:
+	animation = PointFrames()
+
+	coordinate_order = coordinate_order.lower()
+	if len(coordinate_order) != 3 or set(coordinate_order) != {'x', 'y', 'z'}:
+		raise ValueError("coordinate_order must be a 3-letter string containing 'x', 'y', and 'z'")
+
+	with open(file_path, 'rb') as file:
+		magic_number = file.read(4)
+		if magic_number != b'3CPF':
+			raise ValueError('Invalid file format')
+
+		version_number, checksum, total_points, total_frames = struct.unpack('4I', file.read(16))
+
+		data_bytes = file.read()
+		calculated_checksum = crc32(data_bytes) & 0xffffffff
+		if calculated_checksum != checksum:
+			raise ValueError('Data corruption detected')
+
+		offset = 0
+		for _ in range(total_points):
+			r_color, g_color, b_color = struct.unpack_from('3B', data_bytes, offset)
+			animation.points.append(Point(r_color, g_color, b_color))
+			offset += 3
+
+		indices = [coordinate_order.index('x'), coordinate_order.index('y'), coordinate_order.index('z')]
+		for _ in range(total_frames):
+			positions = np.empty((total_points, 3), dtype=np.float32)
+			for point_index in range(total_points):
+				coords = struct.unpack_from('3f', data_bytes, offset)
+				positions[point_index] = [coords[i] for i in indices]
+				offset += 12
+			animation.frames.append(Frame(positions))
+
+	return animation

setup.cfg

@@ -0,0 +1,2 @@
+[metadata]
+description-file = README.md