docs: updating docs for new visualisation

Author: lachlangrose

docs/source/index.rst

@@ -7,6 +7,29 @@ Loop Structural
 ===============
 .. image:: ./images/image823.png
 
+.. important:: **Upgrading from 1.5.x to 1.6.x**
+
+   Version 1.6.x of LoopStructural has been released and there are a number of changes to how the library is used. The main changes are:
+   
+   - The `LavaVuModelViewer` class has been removed and the model visualisation has been ported to `pyvista` using a LoopStructural 
+     wrapped `loopstructuralvisualisation`. Many of the functions have been re-named and can be combined with the `pyvista.Plotter` methods for advanced
+     visualisation. pyvista does not currently allow for interactive plots while using colab notebooks, so `jupyter_backend='static'` is needed.
+   - Datastructures for representing model input/output have been introduced including the `LoopStructural.datatypes.StructuredGrid`,
+     :class:`LoopStructural.datatypes.ValuePoints`, :class:`LoopStructural.datatypes.VectorPoints` and :class:`LoopStructural.datatypes.Surface`. These Datastructures
+     are intended to improve the accessibility of the modelling and allow for easier export into other software packages.
+     All data objects have a `.save` method that allows the user to save the points into various formats including `json`, `csv`, `vtk` and `geoh5`.
+     In the future exporters for gocad and other formats will be added. All objects also have a `.vtk()` method to return a `pyvista.PolyData` object.
+   - The solver options for the interpolators have been removed and only :meth:`scipy.sparse.linalg.cg` and :meth:`scipy.sparse.linalg.lsmr` are supported. 
+     To use an external solver the `external_solver` argument can be provided to the `interpolator.solve` method, usually passed through
+     the `model.create_and_add*` methods. To specify specific arguments to the solver these can be passed through `solver_kwargs` dict.
+   - Improvements have been made to how unconformities are handled and their interaction with faults
+   - A framework for including inequalities into the interpolation has been added but there is no solver that can be used for solving this problem.
+   - A convenience class :class:`LoopStructural.LoopInterpolator` was added for building an implicit function without requiring the :class:`LoopStructural.GeologicalModel`
+   **Please report any bugs or issues on the github repository.**
+ 
+Overview
+========
+
 Loop structural is an open source 3D modelling library providing access to multiple interpolation schemes  with a
 high level and easy to use API for creating geological models. The library has been written for the Loop platform by
 Lachlan Grose at Monash University.
@@ -15,17 +38,7 @@ Loop is an open source 3D probabilistic geological and geophysical modelling pla
 initiated by Geoscience Australia and the OneGeology consortium. The project is funded by Australian territory,
 State and Federal Geological Surveys, the Australian Research Council and the MinEx Collaborative Research Centre.
 
-LoopStructural is the forward geological modelling engine for the loop and contains the classes and functions to manage the various
-elements in a 3D geological model. Including stratigraphy, unconformities, fault and folds. LoopStructural contains
-three native interpolation algorithms:
-
-1. Piecewise-linear interpolation :cite:p:`Frank2007`
-2. Discrete Fold Interpolator :cite:p:`Laurent2016,Grose2017,Grose2018,Grose2019`
-3. Finite Difference Interpolation :cite:p:`Irakarama2020`
-
-and a wrapper for the generalised radial basis functions provided by Surfe :cite:`Hillier2014`. 
 
-.. bibliography::
 
 .. toctree::
    :hidden:

docs/source/user_guide/fault_modelling.rst

@@ -17,9 +17,9 @@ Fault can be added into LoopStructural using the :meth:`LoopStructural.Geologica
                                displacement,
                                fault_slip_vector=None,
                                fault_center = None, 
-                               fault_extent = None, 
-                               fault_influence = None, 
-                               fault_vectical_radius = None, 
+                               fault_major_axis = None, 
+                               fault_minor_axis = None, 
+                               fault_intermediate_axis = None, 
                                faultfunction = None,
                                **kwargs
                                )

docs/source/user_guide/visualisation.rst

@@ -15,19 +15,19 @@ There are four main ways a GeologicalFeature can be visualised.
 
 .. code-block::
 
-    view.add_scalar_field(geological_feature)
+    view.plot_scalar_field(geological_feature)
 
 2. Surfaces extracted from isovalues of the implicit function
 
 .. code-block::
 
-    view.add_isosurface(geological_feature,value=0)
+    view.plot_surface(geological_feature,value=0)
 
 3. Vector field representing the gradient of the implicit function
 
 .. code-block::
 
-    view.add_isosurface(geological_feature)
+    view.plot_surface(geological_feature)
 
 4. Cross section showing the value of the implicit function at a particular location inside the model
 
@@ -43,24 +43,23 @@ When adding to the viewer there are a number of common arguments that can be spe
 
       * - Parameter
         - Options
-      * - name
-        - overwrite the name of the object to be added into the viewer
       * - vmin
         - minimum value for colourmap
       * - vmax
         - maximum value for colourmap
       * - cmap
         - matplotlib colourmap or string with name of matplotlib colourmap e.g. 'rainbow'
+      * - pyvista_kwargs
+        - any arguments to be passed to the :meth:`pyvista.Plotter.add_mesh` method
 
 The default behaviour of the viewer can also be modified.
-To change the resolution of the scalar field or isosurfacing, either set the number of steps in x,y,z or the total number of elements.
+To change the resolution of the scalar field or isosurfacing, either set the number of steps in x,y,z or the total number of elements of tht bounding box
 
 .. code-block::
-
-    view.nsteps = np.array([nx,ny,nz])
-    print(view.nsteps)
-    view.nelements = 1e6
-    print(view.nsteps)
+    model.bounding_box.nsteps = np.array([nx,ny,nz])
+    print(model.bounding_box.nsteps)
+    model.bounding_box.nelements = 1e6
+    print(model.bounding_box.nsteps)
 
 
     
@@ -72,24 +71,24 @@ To add all of the data attached to a GeologicalFeature
 
 .. code-block::
 
-    view.add_data(geological_feature,grad=True,value=True,tang=True,interface=True)
+    view.plot_data(geological_feature,value=True,vector=True,scale=10,pyvista_kwargs={})
 
 Alternatively, points can be added into the model using the:
 
 .. code-block::
 
-    view.add_points(xyz,name='name of viewer object')
+    view.add_points(xyz)
 
 or points with an associated value:
 
 .. code-block::
-    view.add_value_data(xyz,val,name='name of viewer object')
+    view.add_points(xyz,scalars=np.array(values))
 
 or points with an associated vector:
 
 .. code-block::
 
-    view.add_vector_data(xyz,vec,name='name of viewer object')
+    view.add_arrows(xyz,direction)
 
 **Warning, you cannot have two objects in the viewer with the same name**
 
@@ -101,13 +100,13 @@ To add a block model showing the stratigraphic unit distribution, where the valu
 
 .. code-block::
 
-    view.add_model()
+    view.plot_block_model()
 
 alternatively, the surfaces can be added to the visualisation.
 
 .. code-block::
 
-    view.add_model_surfaces(faults=True)
+    view.plot_model_surfaces(faults=True,strati=True)
 
 Where the faults flag allows you to disable visualising the fault surface. 
 This function will add a surface for every stratigraphic unit in the stratigraphic column.
@@ -124,8 +123,8 @@ The LambdaGeologicalFeature is a class allowing for a function describing the va
     def x_function(xyz):
         return xyz[:,0]
     custom_feature = LambdaGeologicalFeature(x_function,name='x feature')
-    view.add_isosurface(custom_feature,value)
-    view.add_scalar_field(custom_feature)
+    view.plot_surface(custom_feature,value)
+    view.plot_scalar_field(custom_feature)
 
 The function passed to the LambdaGeologicalFeature can be as simple or complicated as required. 
 It will be evaluated for the locations within the model that the visualisation requires, usually between the origin and maximum of the geoloical model.