Merge pull request #108 from astrolabsoftware/ui-refactoring

Large API refactoring: introducing spark3D 0.3

Author: JulienPeloton

.gitignore

@@ -10,3 +10,8 @@ __pycache__
 htmlcov
 cov.txt
 .coverage
+build/
+dist/
+MANIFEST*
+pyspark3d.egg-info/
+scripts/

README.md

@@ -13,17 +13,35 @@
 - [08/2018] **Release**: version 0.2.0, 0.2.1 (pyspark3d)
 - [09/2018] **Release**: version 0.2.2
 
-<p align="center"><img width="500" src="https://github.com/astrolabsoftware/spark3D/raw/master/pic/spark3d_lib_0.2.2.png"/>
+<p align="center"><img width="500" src="https://github.com/astrolabsoftware/spark3D/raw/master/pic/spark3d_newapi.png"/>
 </p>
 
+## Rationale
+
+spark3D should be viewed as an extension of the Apache Spark framework, and more specifically the Spark SQL module, focusing on the manipulation of three*-dimensional data sets.
+
+Why would you use spark3D? If you often need to repartition large spatial 3D data sets, or perform spatial queries (neighbour search, window queries, cross-match, clustering, ...), spark3D is for you. It contains optimised classes and methods to do so, and it spares you the implementation time! In addition, a big advantage of all those extensions is to efficiently perform visualisation of large data sets by quickly building a representation of your data set (see more [here](https://astrolabsoftware.github.io/spark3D/)).
+
+spark3D exposes two API: Scala (spark3D) and Python (pyspark3d). The core developments are done in Scala, and interfaced with Python using the great [py4j](https://www.py4j.org/) package. This means pyspark3d might not contain all the features present in spark3D.
+In addition, due to difference between Scala and Python, there might be subtle differences in the two APIs.
+
+While we try to stick to the latest Apache Spark developments, spark3D started with the RDD API and slowly migrated to use the DataFrame API. This process left a huge imprint on the code structure, and low-level layers in spark3D often still use RDD to manipulate the data. Do not be surprised if things are moving, the package is under an active development but we try to keep the user interface as stable as possible!
+
+Last but not least: spark3D is by no means complete, and you are welcome to suggest changes, report bugs or inconsistent implementations, and contribute directly to the package!
+
+Cheers,
+Julien
+
+*Why 3? Because there are already plenty of very good packages dealing with 2D data sets (e.g. [geospark](http://geospark.datasyslab.org/), [geomesa](https://www.geomesa.org/), [magellan](https://magellan.ghost.io/), [GeoTrellis](https://github.com/locationtech/geotrellis), and others), but that was not suitable for many applications such as in astronomy!*
+
 ## Installation and tutorials
 
 ### Scala
 
 You can link spark3D to your project (either spark-shell or spark-submit) by specifying the coordinates:
 
 ```
-spark-submit --packages "com.github.astrolabsoftware:spark3d_2.11:0.2.2"
+spark-submit --packages "com.github.astrolabsoftware:spark3d_2.11:0.3.0"
 ```
 
 ### Python
@@ -38,7 +56,7 @@ Note that we release the assembly JAR with it.
 
 ### More information
 
-See our amazing [website](https://astrolabsoftware.github.io/spark3D/)!
+See our [website](https://astrolabsoftware.github.io/spark3D/)!
 
 ## Contributors
 

docs/01_installation.md

@@ -191,83 +191,6 @@ toto:~$ PYSPARK_DRIVER_PYTHON=ipython pyspark \
   --jars /path/to/target/scala-2.11/spark3D-assembly-0.2.2.jar
 ```
 
-You should be able to import objects:
-
-```python
-In [1]: import pyspark3d
-In [2]: from pyspark3d.geometryObjects import Point3D
-In [3]: Point3D?
-Signature: Point3D(x:float, y:float, z:float, isSpherical:bool) -> py4j.java_gateway.JavaObject
-Docstring:
-Binding around Point3D.scala. For full description,
-see `$spark3d/src/main/scala/com/spark3d/geometryObjects/Point3D.scala`.
-
-By default, the input coordinates are supposed euclidean,
-that is (x, y, z). The user can also work with spherical input coordinates
-(x=r, y=theta, z=phi) by setting the argument isSpherical=true.
-
-Parameters
-----------
-x : float
-    Input X coordinate in Euclidean space, and R in spherical space.
-y : float
-    Input Y coordinate in Euclidean space, and THETA in spherical space.
-z : float
-    Input Z coordinate in Euclidean space, and PHI in spherical space.
-isSpherical : bool
-    If true, it assumes that the coordinates of the Point3D
-    are (r, theta, phi). Otherwise, it assumes cartesian
-    coordinates (x, y, z).
-
-Returns
-----------
-p3d : Point3D instance
-    An instance of the class Point3D.
-
-Example
-----------
-Instantiate a point with spherical coordinates (r, theta, phi)
->>> p3d = Point3D(1.0, np.pi, 0.0, True)
-
-The returned type is JavaObject (Point3D instance)
->>> print(type(p3d))
-<class 'py4j.java_gateway.JavaObject'>
-
-You can then call the method associated, for example
->>> p3d.getVolume()
-0.0
-
-Return the point coordinates
->>> p3d = Point3D(1.0, 1.0, 0.0, False)
->>> p3d.getCoordinatePython()
-[1.0, 1.0, 0.0]
-
-It will be a JavaList by default
->>> coord = p3d.getCoordinatePython()
->>> print(type(coord))
-<class 'py4j.java_collections.JavaList'>
-
-Make it a python list
->>> coord_python = list(coord)
->>> print(type(coord_python))
-<class 'list'>
-
-[Astro] Convert the (theta, phi) in Healpix pixel index:
->>> p3d = Point3D(1.0, np.pi, 0.0, True) # (z, theta, phi)
->>> p3d.toHealpix(2048, True)
-50331644
-
-To see all the available methods:
->>> print(sorted(p3d.__dir__())) # doctest: +NORMALIZE_WHITESPACE
-['center', 'distanceTo', 'equals', 'getClass', 'getCoordinate',
-'getCoordinatePython', 'getEnvelope', 'getHash', 'getVolume',
-'hasCenterCloseTo', 'hashCode', 'intersects', 'isEqual', 'isSpherical',
-'notify', 'notifyAll', 'toHealpix', 'toHealpix$default$2', 'toString',
-'wait', 'x', 'y', 'z']
-File:      ~/Documents/workspace/myrepos/spark3D/pyspark3d/geometryObjects.py
-Type:      function
-```
-
 # Batch mode and provided examples
 
 You can follow the different tutorials: