# blocksets
A python package for performing set operations on layouts of _discrete
space_ in any dimension.
- **Block** is an orthogonal clump of units/pixels (_i.e. a line segment,
rectangle, cuboid, hyper... you get the idea_)
- **BlockSet** takes a layout and resolves it to a disjoint set of **Block**s in
a consistent fashion, regardless of how the layout was composed.
## Why?
You might choose to use a `BlockSet` instead of a `set` of tuples because the
resolution/granularity is sufficiently high to warrant it.
Or in other words, the number of pixels/points being modelled pushes the limits
of the available computing power due to the expanse of the space they take up.
## How?
- Create any layout (as a blockset) using a stacked list of block operations
which `add`, `remove` or `toggle` blocks over the current blockset state.
- Perform the usual set arithmetic `union`, `intersection`, `difference` etc. on
blockset objects.
- Compare 2 blockset objects using the standard set comparison methods and
operators.
- Results are always consistent regardless of how they were constructed.
## Installation
blocksets is [available on pypi.org](https://pypi.org/project/blocksets/) and
can be installed using pip (there are no dependent packages).
`pip install blocksets`
## Usage
Visit [readthedocs](https://blocksets.readthedocs.io/)
Review and run the `example_use.py` module via `python -m blocksets.example_use`
for a few examples, one of which follows here.
### TL;DR
```python
from blocksets import Block, BlockSet
# A block is defined by the co-ordinates of the opposite corners
big_rubik = Block((0, 0, 0), (99999, 99999, 99999))
assert big_rubik.measure == 999970000299999
# A single argument is a unit block
centre_cube = Block((49999, 49999, 49999))
assert centre_cube.measure == 1
# Create a large 3 dimensional cube with the centre missing
bs = BlockSet(3)
bs.add(big_rubik)
bs.remove(centre_cube)
assert bs.measure == 999970000299998
assert len(bs) == 6
sorted_blocks = sorted(bs, key=lambda x: x.norm)
for blk in sorted_blocks:
print(f"{blk:50} {blk.measure}")
```
The resulting space is modelled using 6 objects (effectively tuples) instead of 999970000299998
```text
(0, 0, 0)..(49999, 99999, 99999) 499980000249999
(49999, 0, 0)..(50000, 49999, 99999) 4999850001
(49999, 49999, 0)..(50000, 50000, 49999) 49999
(49999, 49999, 50000)..(50000, 50000, 99999) 49999
(49999, 50000, 0)..(50000, 99999, 99999) 4999850001
(50000, 0, 0)..(99999, 99999, 99999) 499980000249999
```
## Visualisation
An example of 2D set operations on some randomly generated block sets A, B and
drawn using `matplotlib`. See
[readthedocs](https://blocksets.readthedocs.io/en/latest/install_use/#visualize-set-operations)
for code snippet to generate this
<img
src="https://raw.githubusercontent.com/daveisagit/blocksets/main/assets/example_2d_all_set_operations.png"
width="800" height="400" alt="2D - All Set Operations Example">
## Contribution
At the moment it is early days so whilst the foundations are forming I am only
inviting comments which can be given via [github
issues](https://github.com/daveisagit/blocksets/issues)
Raw data
{
"_id": null,
"home_page": null,
"name": "blocksets",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "blocks, compare, cubes, cubiods, dimension, grid, integer, intersect, intervals, lattice, orthogonal, overlap, normalise, pixels, points, ranges, rectangles, sets, space, squares, union, units",
"author": null,
"author_email": "Dave Budd <maildavebudd@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ed/b7/54c998406fdf79390c1ccf2acb3004bb3134d39c8aa1c24b8d7e8a2be3cd/blocksets-0.3.1.tar.gz",
"platform": null,
"description": "# blocksets\n\n\n\n\n\n\nA python package for performing set operations on layouts of _discrete\nspace_ in any dimension.\n\n- **Block** is an orthogonal clump of units/pixels (_i.e. a line segment,\nrectangle, cuboid, hyper... you get the idea_)\n\n- **BlockSet** takes a layout and resolves it to a disjoint set of **Block**s in\n a consistent fashion, regardless of how the layout was composed.\n\n## Why?\n\nYou might choose to use a `BlockSet` instead of a `set` of tuples because the\nresolution/granularity is sufficiently high to warrant it.\n\nOr in other words, the number of pixels/points being modelled pushes the limits\nof the available computing power due to the expanse of the space they take up.\n\n## How?\n\n- Create any layout (as a blockset) using a stacked list of block operations\n which `add`, `remove` or `toggle` blocks over the current blockset state.\n- Perform the usual set arithmetic `union`, `intersection`, `difference` etc. on\n blockset objects.\n- Compare 2 blockset objects using the standard set comparison methods and\n operators.\n- Results are always consistent regardless of how they were constructed.\n\n## Installation\n\nblocksets is [available on pypi.org](https://pypi.org/project/blocksets/) and\ncan be installed using pip (there are no dependent packages).\n\n`pip install blocksets`\n\n## Usage\n\nVisit [readthedocs](https://blocksets.readthedocs.io/)\n\nReview and run the `example_use.py` module via `python -m blocksets.example_use`\nfor a few examples, one of which follows here.\n\n### TL;DR\n\n```python\nfrom blocksets import Block, BlockSet\n\n# A block is defined by the co-ordinates of the opposite corners\nbig_rubik = Block((0, 0, 0), (99999, 99999, 99999)) \nassert big_rubik.measure == 999970000299999\n\n# A single argument is a unit block\ncentre_cube = Block((49999, 49999, 49999))\nassert centre_cube.measure == 1\n\n# Create a large 3 dimensional cube with the centre missing\nbs = BlockSet(3) \nbs.add(big_rubik)\nbs.remove(centre_cube)\n\nassert bs.measure == 999970000299998\nassert len(bs) == 6\n\nsorted_blocks = sorted(bs, key=lambda x: x.norm)\n\nfor blk in sorted_blocks:\n print(f\"{blk:50} {blk.measure}\")\n```\n\nThe resulting space is modelled using 6 objects (effectively tuples) instead of 999970000299998\n\n```text\n(0, 0, 0)..(49999, 99999, 99999) 499980000249999\n(49999, 0, 0)..(50000, 49999, 99999) 4999850001\n(49999, 49999, 0)..(50000, 50000, 49999) 49999\n(49999, 49999, 50000)..(50000, 50000, 99999) 49999\n(49999, 50000, 0)..(50000, 99999, 99999) 4999850001\n(50000, 0, 0)..(99999, 99999, 99999) 499980000249999 \n```\n\n## Visualisation\n\nAn example of 2D set operations on some randomly generated block sets A, B and\ndrawn using `matplotlib`. See\n[readthedocs](https://blocksets.readthedocs.io/en/latest/install_use/#visualize-set-operations)\nfor code snippet to generate this\n\n<img\nsrc=\"https://raw.githubusercontent.com/daveisagit/blocksets/main/assets/example_2d_all_set_operations.png\"\nwidth=\"800\" height=\"400\" alt=\"2D - All Set Operations Example\">\n\n## Contribution\n\nAt the moment it is early days so whilst the foundations are forming I am only\ninviting comments which can be given via [github\nissues](https://github.com/daveisagit/blocksets/issues)\n",
"bugtrack_url": null,
"license": null,
"summary": "Python package for performing set type operations on any layout of discrete space in any dimension.",
"version": "0.3.1",
"project_urls": {
"Documentation": "https://blocksets.readthedocs.io/",
"Homepage": "https://github.com/daveisagit/blocksets",
"Issues": "https://github.com/daveisagit/blocksets/issues"
},
"split_keywords": [
"blocks",
" compare",
" cubes",
" cubiods",
" dimension",
" grid",
" integer",
" intersect",
" intervals",
" lattice",
" orthogonal",
" overlap",
" normalise",
" pixels",
" points",
" ranges",
" rectangles",
" sets",
" space",
" squares",
" union",
" units"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "12a3a7fa5f38a375815a379873d433440a02f8d0f48ffc7e3868bf06eada3ea1",
"md5": "6984a452b5311ce262d2f2688e42aa0d",
"sha256": "4d3f6235b2e26f750e62f716db91270c26998e1eeae1ce2a9a4fac09d2dd2fe0"
},
"downloads": -1,
"filename": "blocksets-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6984a452b5311ce262d2f2688e42aa0d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 15904,
"upload_time": "2024-07-16T10:23:30",
"upload_time_iso_8601": "2024-07-16T10:23:30.101742Z",
"url": "https://files.pythonhosted.org/packages/12/a3/a7fa5f38a375815a379873d433440a02f8d0f48ffc7e3868bf06eada3ea1/blocksets-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "edb754c998406fdf79390c1ccf2acb3004bb3134d39c8aa1c24b8d7e8a2be3cd",
"md5": "b2d277f7038874a4ee8ffa6e68ac4997",
"sha256": "0f6ccc3a7d52aaa27c68eebc98523b19fbbd83d8a7e454e57bc5e4c646e2625e"
},
"downloads": -1,
"filename": "blocksets-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "b2d277f7038874a4ee8ffa6e68ac4997",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 24020,
"upload_time": "2024-07-16T10:23:31",
"upload_time_iso_8601": "2024-07-16T10:23:31.504989Z",
"url": "https://files.pythonhosted.org/packages/ed/b7/54c998406fdf79390c1ccf2acb3004bb3134d39c8aa1c24b8d7e8a2be3cd/blocksets-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-16 10:23:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "daveisagit",
"github_project": "blocksets",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "blocksets"
}
JSON
