Metadata-Version: 2.1
Name: regOct
Version: 1.1.2
Summary: A module implementing octrees for python
Home-page: https://github.com/runoverPy/regOct
Author: runover
License: MIT
Description: # regOct
        an implementation of an ordered octree system
        
        ## Design principles
        0. Provide an effective, comprehensive storage medium for cubic, three-dimensional data.
        1. The order in which the commands are stored in the file imply the position at which they are executed.
        2. State checks within the octree are linear and processor unintensive.
        3. The Octree is a self-contained system. All information regarding the octree is stored in the file.
        
        
        
        # Use
        ## 1. General use
        Every octree has an integer "level", which defines its size. For a given level, the octree takes the form of a cube with ranges of 0 - 2**level.
        ```python 
        regoct.Octree(level) -> Octree
        
        # setting a value:
        octree[(x, y, z, level)] = new_value
        # level may be omitted if it is 0:
        octree[(x, y, z)] = new_value
        
        # getting a value:
        value = octree[(x, y, z)]
        ```
        
        ## 2. Basic octree IO
        In case it is necessary to preserve an octree for later use, it may be saved and loaded to the filesystem via as shown below:
        ```python
        import regoct
        
        original_octree = Octree(2)
        # load information into octree
        
        file_path = "file_path.onc"
        regoct.save(octree, file_path)
        loaded_octree = regoct.load(file_path)
        
        assert original_octree == loaded_octree
        ```
        This however has a major caveat: the octrees serialized this way may only have internal values of python's base data types:
        ```python
        None(wip), Ellipsis(wip), bool(wip), int, float, complex, str, list, dict, set 
        ```
        This is addressed followingly.
        ## 3. Advanced octree IO
        
        regoct provides a API to modify the serialization process. This is useful for implementing routines for class instances.
        
        The ABC regoct.Interface supplies the tools for implementing the API. It requires the methods `to_file(obj, saver: "regoct.SavingStream")` and `from_file(cls, loader: "regoct.LoadingStream")`, where the params **saver** and **loader** provide access to the data using a set of methods. These methods in loader and saver mirror each other and are as follows:
        |regoct.SavingStream | regoct.LoadingStream | description|
        |--------------------|----------------------|-------------|
        | saver.convert(value) | loader.convert() -> any | dynamic conversion |
        | saver.i8(value) | loader.i8() -> int | 8-bit signed integer |
        | saver.i16(value) | loader.i16() -> int | 16-bit signed integer |
        | saver.i32(value) | loader.i32() -> int | 32-bit signed integer |
        | saver.i64(value) | loader.i64() -> int | 64-bit signed integer |
        | saver.u8(value) | loader.u8() -> int | 8-bit unsigned integer | 
        | saver.u16(value) | loader.u16() -> int | 16-bit unsigned integer |
        | saver.u32(value) | loader.u32() -> int | 32-bit unsigned integer |
        | saver.u64(value) | loader.u64() -> int | 64-bit unsigned integer |
        | saver.f32(value) | loader.f32() -> float | 32-bit float |
        | saver.f64(value) | loader.f64() -> float | 64-bit float |
        | saver.c64(value) | loader.c64() -> complex | 2x 32-bit float complex number |
        | saver.c128(value) | loader.c128() -> complex | 2x 64-bit float complex number |
        | saver.Str(value) | loader.Str() -> str | variable-length utf-8 string |
        | saver.List(value) | loader.List() -> list | variable-length dynamic-type list |
        | saver.Dict(value) | loader.Dict() -> dict | variable-length dynamic-type dict | 
        | saver.Set(value) | loader.Set() -> set | variable-length dynamic-type set |
        
        Be aware that the order in which these methods are called in the to_file and from_file methods should be equal to eachother.
        
        ```python 
        import regoct
        from regoct import Interface, SavingStream, LoadingStream
        
        class DataPacket(Interface):
            def __init__(self, *args, **kwds):...
        
            def to_file(obj, saver: SavingStream):...
        
            def from_file(cls, loader: LoadingStream):...
        
        
        original_octree = regoct.Octree(2)
        # load information into octree
        
        file_path = "file_path.onc"
        DataPacket.save(octree, file_path)
        loaded_octree = DataPacket.load(file_path)
        
        assert original_octree == loaded_octree
        ``` 
        
        ## Visualisation:
        The module has an interactable viewer to render octrees in 3d. 
        Currently, this is done with the statement `regoct.Display(octree).main()`, but since this is very verbose, expect it to change.
        
        
        ## And now for something completely different
        ![**no one expects the spanish inquisition**](https://static.wikia.nocookie.net/montypython/images/f/ff/Spanish_Inquisition.jpg/revision/latest?cb=20180629171423)
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.0
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3, <4
Description-Content-Type: text/markdown
