doc

.gitlab-ci.yml

@@ -85,6 +85,7 @@ pages:
     - make
     - cp libseamsh.so ../../seamsh
     - cd ../../doc
+    - python3 gen_examples.p
     - make html
     - mv _build/html ../public
   artifacts:

Readme.rst

-Seamsh_ is a python library wrapping gmsh_, gdal_  and scipy_ to simplify the generation of unstructured meshes. It is primarily developed for coastal ocean simulations but can be used in other GIS contexts.
+Seamsh_ is a Python library wrapping gmsh_, gdal_  and scipy_ to simplify the generation of unstructured meshes. While primarily developed for coastal ocean simulations, it can be used in other GIS contexts.
 
-Seamsh allows to :
+Main Features :
 
-- import ESRI shapefiles to define tagged domain boundaries, interior lines and interior points
-- define arbitrary mesh elements size fields based on distances from lines or raster files
-- create a low-resolution valid topology from high-resolution non conformal (i.e. intersecting) data
+- Import ESRI shapefiles to define tagged domain boundaries, interior lines and interior points.
+- Define arbitrary mesh elements size fields based on distances from lines or raster files.
+- Create a low-resolution valid topology from high-resolution non conformal (i.e. intersecting) data.
+
+Seamesh is distributed under the GPL_. See the gitlab page of the project for the `source code`_  and `bug reports`_. The documentation_ contains examples, Python API references and installation instructions.
+Binary packages for 64 bits linux, windows and OSX are available on pypi_.
 
 .. _gmsh : https://www.gmsh.info
 .. _gdal : https://gdal.org
 .. _scipy : https://www.scipy.org
 .. _Seamsh : https://git.immc.ucl.ac.be/jlambrechts/seamsh
-
-Seamesh is distributed under the GPL_. See the gitlab page of the project for the `source code`__ , documentation__ and `bug reports`__
-Binary packages for 64 bits linux, windows and OSX are available on pypi_.
-
-__ https://git.immc.ucl.ac.be/jlambrechts/seamsh
-__ http://jlambrechts.git-page.immc.ucl.ac.be/seamsh
-__ https://git.immc.ucl.ac.be/jlambrechts/seamsh/-/issues
+.. _source code : https://git.immc.ucl.ac.be/jlambrechts/seamsh
+.. _documentation : http://jlambrechts.git-page.immc.ucl.ac.be/seamsh
+.. _bug reports : https://git.immc.ucl.ac.be/jlambrechts/seamsh/-/issues
 .. _GPL : https://www.gnu.org/licenses/gpl-3.0.html
 .. _pypi : https://test.pypi.org/project/seamsh

doc/conf.py

@@ -33,7 +33,11 @@ if commit_tag and (commit_tag.startswith("v-") or commit_tag.startswith("w-")):
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc','sphinx.ext.napoleon','sphinx_autodoc_typehints']
+extensions = [
+        'sphinx.ext.autodoc',
+        'sphinx.ext.napoleon',
+        'sphinx_autodoc_typehints',
+        ]
 
 napoleon_google_docstring = True
 napoleon_numpy_docstring = False

doc/demo.rst → doc/examples.rst

-Installation
-============
-
-
 Examples
 ========
 
+.. toctree::
+   :glob:
+
+   examples/*

doc/gen_examples.py

+import glob
+import shutil
+import os
+try :
+    shutil.rmtree("examples")
+except :
+    pass
+os.makedirs("examples")
+
+for filename in glob.glob("../examples/*.py") :
+    inrst = True
+    with open(filename, "r") as f:
+        bname = os.path.basename(filename)[:-3]
+        with open("examples/"+bname+".rst","w") as fout :
+            fout.write("Download :download:`this example <../%s>`.\n"%filename)
+            for i,line in enumerate(f) :
+                line = line[:-1]
+                lstrip = line.strip()
+                if lstrip == "# %%" :
+                    inrst = True
+                    fout.write("\n")
+                    continue
+                if (not lstrip and inrst) or i == 0:
+                    fout.write("\n.. code-block:: python\n  \n")
+                    inrst = False
+                    continue
+                if inrst :
+                    fout.write(line[2:]+"\n")
+                else :
+                    fout.write("  "+line+"\n")
+
+
+

doc/index.rst

-Seamsh Documentation
-====================
+Seamsh
+======
 
 .. include:: ../Readme.rst
 
-.. include:: demo.rst
-
-.. include:: modules.rst
-
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+   self
+   install
+   examples
+   seamsh 
 
 * :ref:`genindex`
 

doc/install.rst

+Installation
+============
+Dependencies
+------------
+Seamsh depends on the following python3 packages:
+
+- `gmsh-dev <https://pypi.org/project/gmsh-dev>`_
+- `gdal <https://pypi.org/project/gdal>`_
+- `scipy <https://pypi.org/project/scipy>`_
+
+Depending on your platform, gdal and scipy can probably be installed directly from your package manager, otherwise pip can be used (follow the links above for installation instructions).
+
+To install gmsh-dev, follow the instuctions on the gmsh-dev_ pypi page. Do not forget, to uninstall other previous gmsh installations. Check that gmsh-dev is correctly installed with the following command.
+
+.. code-block:: bash
+
+   python3 -c "import gmsh;gmsh.initialize();print(gmsh.option.getString('General.Version'))"
+
+The output should be a version number >= 3.6.1.
+On some platforms, it is necessary to set the python path manually after installation e.g. :
+
+.. code-block:: bash
+
+   export "PYTONPATH=$HOME/.local/lib/python3.8/site-packages/gmsh-git-Linux64-sdk/lib/:$PYTHONPATH"
+
+
+Installation with pip
+---------------------
+Pre-compiled seamsh libraries are provided for 64bit linux, windows and OSX.
+
+.. code-block:: bash 
+
+   pip3 install seammsh
+
+Installation from sources
+-------------------------
+To build the package from sources, it is necessary to first compile the (small) seamsh C library. For example on linux/OSX :
+
+.. code-block:: bash 
+  
+   git clone https://git.immc.ucl.ac.be/jlambrechts/seamsh
+   cd seamsh/seamshlib
+   mkdir build
+   cd build
+   cmake .. -DCMAKE_BUILD_TYPE=Release
+   make
+   cp *.so ../../seamsh
+   cd ../../
+   python3 setup.py build

doc/modules.rst

-Pyhton api
-==========
-
-.. toctree::
-   :maxdepth: 4
-
-   seamsh

doc/seamsh.rst

-seamsh package
-==============
+API Reference
+=============
 
 .. toctree::
    :maxdepth: 4

examples/1-simple.py

+# seamsh - Copyright (C) <2010-2020>
+# <Universite catholique de Louvain (UCL), Belgium
+# 	
+# List of the contributors to the development of seamsh: see AUTHORS file.
+# Description and complete License: see LICENSE file.
+# 	
+# This program (seamsh) is free software: 
+# you can redistribute it and/or modify it under the terms of the GNU Lesser General 
+# Public License as published by the Free Software Foundation, either version
+# 3 of the License, or (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with this program (see COPYING file).  If not, 
+# see <http://www.gnu.org/licenses/>.
+
+# %%
+# my super example simple
+# =======================
+
+import seamsh
+import numpy as np
+from osgeo import osr 
+
+def mesh_size(x) :
+    return (0.0025+(1+np.sin(4*np.pi*x[:,1]*np.pi*x[:,0]))*0.01)*2
+
+domain_srs = osr.SpatialReference()
+domain_srs.ImportFromEPSG(4326)
+
+domain = seamsh.Domain(domain_srs)
+domain.add_curve([[0,0],[-0.2,0.25],[-0.2,0.75],[0,1]],
+        "wall",domain_srs,curve_type=seamsh.SPLINE)
+domain.add_curve([[0,1],[0.25,1.2],[0.75,1.2],[1,1]],
+        "wall1",domain_srs,curve_type=seamsh.BSPLINE)
+domain.add_curve([[0,0],[0.25,-0.2],[0.75,-0.2],[1,0]],
+        "wall2",domain_srs,curve_type=seamsh.STRICTPOLYLINE)
+domain.add_curve([[1,1],[1.2,0.75],[1.2,0.25],[1,0]],
+        "wall3",domain_srs,curve_type=seamsh.STRICTPOLYLINE)
+domain.add_curve([[0.4,0.6],[0.6,0.6],[0.6,0.4],[0.4,0.4],[0.4,0.6]],
+        "wallin",domain_srs,curve_type=seamsh.BSPLINE)
+domain.build_topology()
+
+seamsh.mesh_gmsh(domain,"test.msh",mesh_size)

examples/2-shapefiles.py

+# %%
+# my super example
+# ================
+
+import os
+import urllib.request
+import tarfile
+if not os.path.isdir("data") :
+    urllib.request.urlretrieve("ftp://braque.mema.ucl.ac.be/seamsh/data-test-1.tar.gz", "data-test-1.tar.gz")
+    f = tarfile.open("data-test-1.tar.gz","r:*")
+    f.extractall()
+
+import seamsh
+from seamsh.geometry import CurveType
+import seamsh.geometry
+import numpy as np
+from osgeo import osr 
+
+# %%
+# with comments in the middle
+
+def mesh_size(x,projection) :
+    s_coast = np.clip((dist_coast_field(x,projection)-400)*0.5,200,5000)
+    s_porquerolles = np.clip((dist_porquerolles_field(x,projection)-200)*0.5,50,5000)
+    return np.minimum(s_coast,s_porquerolles)
+
+domain_srs = osr.SpatialReference()
+
+domain_srs.ImportFromEPSG(32631)
+#domain_srs.ImportFromProj4("+proj=utm +ellps=WGS84 +zone=31")
+
+domain = seamsh.geometry.Domain(domain_srs)
+domain.add_boundary_curves_shp("data/data_no_duplicate.shp","physical",CurveType.POLYLINE)
+#domain.add_interior_curves_shp("data/interior.shp",None,CurveType.STRICTPOLYLINE)
+#domain.add_interior_points_shp("data/interior.shp")
+bath_field = seamsh.field.Raster("data/medit.tiff")
+dist_coast_field = seamsh.field.Distance(domain,100,["coast","island"])
+dist_porquerolles_field = seamsh.field.Distance(domain,20,["porquerolles"])
+#coarse = seamsh.geometry.coarsen_boundaries(domain,(8e5,4.68e6),domain_srs,mesh_size,20)
+seamsh.gmsh.mesh(domain,"test.msh",mesh_size,intermediate_file_name="log")
+seamsh.gmsh.convert_to_gis("test.msh",domain_srs,"test.gpkg")
+
+seamsh.gmsh.gmsh.model.add("test")
+seamsh.gmsh.gmsh.open("test.msh")
+tag,nodes = seamsh.gmsh.gmsh.model.mesh.getElementsByType(2)
+ntri = len(tag)
+print("ntri",ntri)
+assert(ntri>40000 and ntri<41000)