resqpy 4.14.2__py3-none-any.whl → 5.1.6__py3-none-any.whl

resqpy/surface/_surface.py

@@ -8,6 +8,7 @@ import logging
 log = logging.getLogger(__name__)
 
 import numpy as np
+import math as maths
 
 import resqpy.crs as rqc
 import resqpy.lines as rql
@@ -47,7 +48,7 @@ class Surface(rqsb.BaseSurface):
                  originator = None,
                  extra_metadata = {}):
         """Create an empty Surface object (RESQML TriangulatedSetRepresentation).
-        
+
         Optionally populates from xml, point set or mesh.
 
         arguments:
@@ -122,6 +123,76 @@ class Surface(rqsb.BaseSurface):
             self.set_from_mesh_file(mesh_file, mesh_format, quad_triangles = quad_triangles)
         elif tsurf_file is not None:
             self.set_from_tsurf_file(tsurf_file)
+        self._load_normal_vector_from_extra_metadata()
+
+    @classmethod
+    def from_list_of_patches(cls, model, patch_list, title, crs_uuid = None, extra_metadata = None):
+        """Create a Surface from a prepared list of TriangulatedPatch objects.
+
+        arguments:
+            - model (Model): the model to which the surface will be associated
+            - patch_list (list of TriangulatedPatch): the list of patches to be combined to form the surface
+            - title (str): the citation title for the new surface
+            - crs_uuid (uuid, optional): the uuid of a crs in model which the points are deemed to be in
+            - extra_metadata (dict of (str: str), optional): extra metadata to add to the new surface
+
+        returns:
+            - new Surface comprised of a patch for each entry in the patch list
+
+        notes:
+            - the triangulated patch objects are used directly in the surface
+            - the patches should not have had their hdf5 data written yet
+            - the patch index values will be set, with any previous values ignored
+            - the patches will be hijacked to the target model if their model is different
+            - each patch will have its points converted in situ into the surface crs
+            - if the crs_uuid argument is None, the crs_uuid is taken from the first patch
+        """
+        assert len(patch_list) > 0, 'attempting to create Surface from empty patch list'
+        if crs_uuid is None:
+            crs_uuid = patch_list[0].crs_uuid
+            if model.uuid(uuid = crs_uuid) is None:
+                model.copy_uuid_from_other_model(patch_list[0].model, crs_uuid)
+        surf = cls(model, title = title, crs_uuid = crs_uuid, extra_metadata = extra_metadata)
+        surf.patch_list = patch_list
+        surf.crs_uuid = crs_uuid
+        crs = rqc.Crs(model, uuid = crs_uuid)
+        for i, patch in enumerate(surf.patch_list):
+            assert patch.points is not None, f'points missing in patch {i} when making surface {title}'
+            patch.index = i
+            patch._set_t_type()
+            if not bu.matching_uuids(patch.crs_uuid, crs_uuid):
+                p_crs = rqc.Crs(patch.model, uuid = patch.crs_uuid)
+                p_crs.convert_array_to(crs, patch.points)
+            patch.model = model
+        return surf
+
+    @classmethod
+    def from_list_of_patches_of_triangles_and_points(cls, model, t_p_list, title, crs_uuid, extra_metadata = None):
+        """Create a Surface from a prepared list of pairs of (triangles, points).
+
+        arguments:
+            - model (Model): the model to which the surface will be associated
+            - t_p_list (list of (numpy int array, numpy float array)): the list of patches of triangles and points;
+              the int arrays have shape (N, 3) being the triangle vertex indices of points; the float array has
+              shape (M, 3) being the xyx values for the points, in the crs identified by crs_uuid
+            - title (str): the citation title for the new surface
+            - crs_uuid (uuid): the uuid of a crs in model which the points are deemed to be in
+            - extra_metadata (dict of (str: str), optional): extra metadata to add to the new surface
+
+        returns:
+            - new Surface comprised of a patch for each entry in the list of pairs of triangles and points data
+
+        note:
+            - each entry in the t_p_list will have its own patch in the resulting surface, indexed in order of list
+        """
+        assert t_p_list, f'no triangles and points pairs in list when generating surface: {title}'
+        assert crs_uuid is not None
+        patch_list = []
+        for i, (t, p) in enumerate(t_p_list):
+            patch = rqs.TriangulatedPatch(model, patch_index = i, crs_uuid = crs_uuid)
+            patch.set_from_triangles_and_points(t, p)
+            patch_list.append(patch)
+        return cls.from_list_of_patches(model, patch_list, title, crs_uuid = crs_uuid, extra_metadata = extra_metadata)
 
     @classmethod
     def from_tri_mesh(cls, tri_mesh, exclude_nans = False):
@@ -272,69 +343,169 @@ class Surface(rqsb.BaseSurface):
 
         self.model = parent_model
 
-    def triangles_and_points(self):
-        """Returns arrays representing combination of all the patches in the surface.
+    def number_of_patches(self):
+        """Returns the number of patches present in the surface."""
+
+        self.extract_patches(self.root)
+        return len(self.patch_list)
+
+    def triangles_and_points(self, patch = None, copy = False):
+        """Returns arrays representing one patch or a combination of all the patches in the surface.
+
+        arguments:
+           patch (int, optional): patch index; if None, combined arrays for all patches are returned
+           copy (bool, default False): if True, a copy of the arrays is returned; if False, the cached
+              arrays are returned
 
         returns:
            tuple (triangles, points):
               triangles (int array of shape[:, 3]): integer indices into points array,
-                  being the nodes of the corners of the triangles;
+                 being the nodes of the corners of the triangles;
               points (float array of shape[:, 3]): flat array of xyz points, indexed by triangles
 
         :meta common:
         """
 
-        if self.triangles is not None:
-            return (self.triangles, self.points)
         self.extract_patches(self.root)
-        points_offset = 0
-        for triangulated_patch in self.patch_list:
-            (t, p) = triangulated_patch.triangles_and_points()
-            if points_offset == 0:
-                self.triangles = t.copy()
-                self.points = p.copy()
+        if patch is None:
+            if self.triangles is None or self.points is None:
+                if self.triangles is None:
+                    points_offset = 0
+                    for triangulated_patch in self.patch_list:
+                        (t, p) = triangulated_patch.triangles_and_points()
+                        if points_offset == 0:
+                            self.triangles = t
+                            self.points = p
+                        else:
+                            self.triangles = np.concatenate((self.triangles, t.copy() + points_offset))
+                            self.points = np.concatenate((self.points, p))
+                        points_offset += p.shape[0]
+            if copy:
+                return (self.triangles.copy(), self.points.copy())
             else:
-                self.triangles = np.concatenate((self.triangles, t.copy() + points_offset))
-                self.points = np.concatenate((self.points, p.copy()))
-            points_offset += p.shape[0]
-        return (self.triangles, self.points)
+                return (self.triangles, self.points)
+        assert 0 <= patch < len(self.patch_list),  \
+            ValueError(f'patch index {patch} out of range for surface with {len(self.patch_list)} patches')
+        return self.patch_list[patch].triangles_and_points(copy = copy)
+
+    def patch_index_for_triangle_index(self, triangle_index):
+        """Returns the patch index for a triangle index (as applicable to triangles_and_points() triangles)."""
+        if triangle_index is None or triangle_index < 0:
+            return None
+        self.extract_patches(self.root)
+        if not self.patch_list:
+            return None
+        for i, patch in enumerate(self.patch_list):
+            triangle_index -= patch.triangle_count
+            if triangle_index < 0:
+                return i
+        return None
+
+    def patch_indices_for_triangle_indices(self, triangle_indices, lazy = True):
+        """Returns array of patch indices for array of triangle indices (as applicable to triangles_and_points() triangles)."""
+        self.extract_patches(self.root)
+        if not self.patch_list:
+            return np.full(triangle_indices.shape, -1, dtype = np.int8)
+        patch_count = len(self.patch_list)
+        dtype = (np.int8 if patch_count < 127 else np.int32)
+        if lazy and patch_count == 1:
+            return np.zeros(triangle_indices.shape, dtype = np.int8)
+        patch_limits = np.zeros(patch_count, dtype = np.int32)
+        t_count = 0
+        for p_i in range(patch_count):
+            t_count += self.patch_list[p_i].triangle_count
+            patch_limits[p_i] = t_count
+        patches = np.empty(triangle_indices.shape, dtype = dtype)
+        patches[:] = np.digitize(triangle_indices, patch_limits, right = False)
+        if not lazy:
+            patches[np.logical_or(triangle_indices < 0, patches == patch_count)] = -1
+        return patches
+
+    def decache_triangles_and_points(self):
+        """Removes the cached composite triangles and points arrays."""
+        self.points = None
+        self.triangles = None
+
+    def triangle_count(self, patch = None):
+        """Return the numner of triangles in this surface, or in one patch.
 
-    def triangle_count(self):
-        """Return the numner of triangles in this surface."""
+        arguments:
+           patch (int, optional): patch index; if None, a combined triangle count for all patches is returned
+
+        returns:
+           int being the number of trianges in the patch (if specified) or in all the patches
+        """
 
         self.extract_patches(self.root)
-        if not self.patch_list:
-            return 0
-        return np.sum([tp.triangle_count for tp in self.patch_list])
+        if patch is None:
+            if not self.patch_list:
+                return 0
+            return np.sum([tp.triangle_count for tp in self.patch_list])
+        assert 0 <= patch < len(self.patch_list),  \
+            ValueError(f'patch index {patch} out of range for surface with {len(self.patch_list)} patches in triangle_count')
+        return self.patch_list[patch].triangle_count
+
+    def node_count(self, patch = None):
+        """Return the number of nodes (points) used in this surface, or in one patch.
+
+        arguments:
+           patch (int, optional): patch index; if None, a combined node count for all patches is returned
 
-    def node_count(self):
-        """Return the number of nodes (points) used in this surface."""
+        returns:
+           int being the number of nodes in the patch (if specified) or in all the patches
+
+        note:
+           a multi patch surface might have more than one node colocated; this method will treat such coincident nodes
+           as separate nodes
+        """
 
         self.extract_patches(self.root)
-        if not self.patch_list:
-            return 0
-        return np.sum([tp.node_count for tp in self.patch_list])
+        if patch is None:
+            if not self.patch_list:
+                return 0
+            return np.sum([tp.node_count for tp in self.patch_list])
+        assert 0 <= patch < len(self.patch_list),  \
+            ValueError(f'patch index {patch} out of range for surface with {len(self.patch_list)} patches in node_count')
+        return self.patch_list[patch].node_count
 
     def change_crs(self, required_crs):
         """Changes the crs of the surface, also sets a new uuid if crs changed.
 
-        note:
+        notes:
            this method is usually used to change the coordinate system for a temporary resqpy object;
-           to add as a new part, call write_hdf5() and create_xml() methods
+           to add as a new part, call write_hdf5() and create_xml() methods;
+           patches are maintained by this method;
+           normal vector extra metadata item is updated if present; rotation matrix is removed
         """
 
         old_crs = rqc.Crs(self.model, uuid = self.crs_uuid)
         self.crs_uuid = required_crs.uuid
-        if required_crs == old_crs or not self.patch_list:
+        if bu.matching_uuids(required_crs.uuid, old_crs.uuid) or not self.patch_list:
             log.debug(f'no crs change needed for {self.title}')
             return
+        equivalent_crs = (required_crs == old_crs)
         log.debug(f'crs change needed for {self.title} from {old_crs.title} to {required_crs.title}')
         for patch in self.patch_list:
-            patch.triangles_and_points()
-            required_crs.convert_array_from(old_crs, patch.points)
+            assert bu.matching_uuids(patch.crs_uuid, old_crs.uuid)
+            if not equivalent_crs:
+                patch.triangles_and_points()
+                required_crs.convert_array_from(old_crs, patch.points)
             patch.crs_uuid = self.crs_uuid
         self.triangles = None  # clear cached arrays for surface
         self.points = None
+        if not equivalent_crs:
+            if self.extra_metadata.pop('rotation matrix', None) is not None:
+                log.debug(f'discarding rotation matrix extra metadata during crs change of: {self.title}')
+            self._load_normal_vector_from_extra_metadata()
+            if self.normal_vector is not None:
+                if required_crs.z_inc_down != old_crs.z_inc_down:
+                    self.normal_vector[2] = -self.normal_vector[2]
+                theta = (wam.convert(required_crs.rotation, required_crs.rotation_units, 'dega') -
+                         wam.convert(old_crs.rotation, old_crs.rotation_units, 'dega'))
+                if not maths.isclose(theta, 0.0):
+                    self.normal_vector = vec.rotate_vector(vec.rotation_matrix_3d_axial(2, theta), self.normal_vector)
+                self.extra_metadata['normal vector'] = str(
+                    f'{self.normal_vector[0]},{self.normal_vector[1]},{self.normal_vector[2]}')
         self.uuid = bu.new_uuid()  # hope this doesn't cause problems
         assert self.root is None
 
@@ -381,7 +552,7 @@ class Surface(rqsb.BaseSurface):
         self.uuid = bu.new_uuid()
 
     def set_to_split_surface(self, large_surface, line, delta_xyz):
-        """Populate this (empty) surface with a version of a larger surface split by an xy line.
+        """Populate this (empty) surface with a version of a larger surface split by a straight xy line.
 
         arguments:
             large_surface (Surface): the larger surface, a copy of which is to be split
@@ -399,13 +570,14 @@ class Surface(rqsb.BaseSurface):
         t, p = large_surface.triangles_and_points()
         assert p.ndim == 2 and p.shape[1] == 3
         pp = np.concatenate((p, line), axis = 0)
-        tp = np.empty(p.shape, dtype = int)
+        t_type = np.int32 if len(pp) <= 2_147_483_647 else np.int64
+        tp = np.empty(p.shape, dtype = t_type)
         tp[:, 0] = len(p)
         tp[:, 1] = len(p) + 1
-        tp[:, 2] = np.arange(len(p), dtype = int)
+        tp[:, 2] = np.arange(len(p), dtype = t_type)
         cw = vec.clockwise_triangles(pp, tp)
-        pai = np.where(cw >= 0.0, True, False)  # bool mask over p
-        pbi = np.where(cw <= 0.0, True, False)  # bool mask over p
+        pai = (cw >= 0.0)  # bool mask over p
+        pbi = (cw <= 0.0)  # bool mask over p
         tap = pai[t]
         tbp = pbi[t]
         ta = np.any(tap, axis = 1)  # bool array over t
@@ -414,11 +586,11 @@ class Surface(rqsb.BaseSurface):
         # here we stick the two halves together into a single patch
         # todo: keep as two patches as required by RESQML business rules
         p_combo = np.empty((0, 3))
-        t_combo = np.empty((0, 3), dtype = int)
+        t_combo = np.empty((0, 3), dtype = t_type)
         for i, tab in enumerate((ta, tb)):
             p_keep = np.unique(t[tab])
             # note new point index for each old point that is being kept
-            p_map = np.full(len(p), -1, dtype = int)
+            p_map = np.full(len(p), -1, dtype = t_type)
             p_map[p_keep] = np.arange(len(p_keep))
             # copy those unique points into a trimmed points array
             points_trimmed = p[p_keep].copy()
@@ -435,17 +607,24 @@ class Surface(rqsb.BaseSurface):
 
         self.set_from_triangles_and_points(t_combo, p_combo)
 
-    def distinct_edges(self):
-        """Returns a numpy int array of shape (N, 2) being the ordered node pairs of distinct edges of triangles."""
+    def distinct_edges(self, patch = None):
+        """Returns a numpy int array of shape (N, 2) being the ordered node pairs of distinct edges of triangles.
+
+        arguments:
+           patch (int, optional): patch index; if None, a combination of edges for all patches is returned
+        """
 
-        triangles, _ = self.triangles_and_points()
+        triangles, _ = self.triangles_and_points(patch = patch)
         assert triangles is not None
         unique_edges, _ = triangulate.edges(triangles)
         return unique_edges
 
-    def distinct_edges_and_counts(self):
+    def distinct_edges_and_counts(self, patch = None):
         """Returns unique edges as pairs of point indices, and a count of uses of each edge.
 
+        arguments:
+           patch (int, optional): patch index; if None, combined results for all patches are returned
+
         returns:
             numpy int array of shape (N, 2), numpy int array of shape (N,)
             where 2D array is list-like sorted points index pairs for unique edges
@@ -453,14 +632,39 @@ class Surface(rqsb.BaseSurface):
 
         notes:
             first entry in each pair is always the lower of the two point indices;
-            for well formed surfaces, the count should everywhere be zero or one;
+            for well formed surfaces, the count should everywhere be one or two;
             the function does not attempt to detect coincident points
         """
 
-        triangles, _ = self.triangles_and_points()
+        triangles, _ = self.triangles_and_points(patch = patch)
         assert triangles is not None
         return triangulate.edges(triangles)
 
+    def edge_lengths(self, required_uom = None, patch = None):
+        """Returns float array of shape (N, 3) being triangle edge lengths.
+
+        arguments:
+            required_uom (str, optional): the required length uom for the resulting edge lengths; default is crs xy units
+            patch (int, optional): patch index; if None, edge lengths for all patches are returned
+
+        returns:
+            numpy float array of shape (N, 3) where N is the number of triangles
+        """
+
+        t, p = self.triangles_and_points(patch = patch)
+        crs = rqc.Crs(self.model, uuid = self.crs_uuid)
+        if required_uom is None:
+            required_uom = crs.xy_units
+        if crs.xy_units != required_uom or crs.z_units != required_uom:
+            p = p.copy()
+            wam.convert_lengths(p[:, :2], crs.xy_units, required_uom)
+            wam.convert_lengths(p[:, 2], crs.z_units, required_uom)
+        t_end = np.empty_like(t)
+        t_end[:, :2] = t[:, 1:]
+        t_end[:, 2] = t[:, 0]
+        edge_v = p[t_end, :] - p[t, :]
+        return vec.naive_lengths(edge_v)
+
     def set_from_triangles_and_points(self, triangles, points):
         """Populate this (empty) Surface object from an array of triangle corner indices and an array of points."""
 
@@ -468,6 +672,22 @@ class Surface(rqsb.BaseSurface):
         tri_patch.set_from_triangles_and_points(triangles, points)
         self.patch_list = [tri_patch]
         self.uuid = bu.new_uuid()
+        self.triangles = triangles.copy()
+        self.points = points.copy()
+
+    def set_multi_patch_from_triangles_and_points(self, triangles_and_points_list):
+        """Populate this (empty) Surface object from a list of paits: array of triangle corner indices, array of points."""
+
+        self.patch_list = []
+        self.trianges = None
+        self.points = None
+        for patch, entry in enumerate(triangles_and_points_list):
+            assert len(entry) == 2, 'expecting pair of arrays (triangles, points) for each patch'
+            triangles, points = entry
+            tri_patch = rqstp.TriangulatedPatch(self.model, patch_index = patch, crs_uuid = self.crs_uuid)
+            tri_patch.set_from_triangles_and_points(triangles, points)
+            self.patch_list.append(tri_patch)
+        self.uuid = bu.new_uuid()
 
     def set_from_point_set(self,
                            point_set,
@@ -480,7 +700,8 @@ class Surface(rqsb.BaseSurface):
                            flange_radial_distance = None,
                            flange_inner_ring = False,
                            saucer_parameter = None,
-                           make_clockwise = False):
+                           make_clockwise = False,
+                           normal_vector = None):
         """Populate this (empty) Surface object with a Delaunay triangulation of points in a PointSet object.
 
         arguments:
@@ -489,9 +710,10 @@ class Surface(rqsb.BaseSurface):
               convex; reduce to 1.0 to allow slightly more concavities; increase to 100.0 or more for very little
               chance of even a slight concavity
            reorient (bool, default False): if True, a copy of the points is made and reoriented to minimise the
-              z range (ie. z axis is approximate normal to plane of points), to enhace the triangulation
+              z range (ie. z axis is approximate normal to plane of points), to enhace the triangulation; if a
+              normal_vector is supplied, the reorientation is based on that instead of minimising z
            reorient_max_dip (float, optional): if present, the reorientation of perspective off vertical is
-              limited to this angle in degrees
+              limited to this angle in degrees; ignored if normal_vector is specified
            extend_with_flange (bool, default False): if True, a ring of points is added around the outside of the
               points before the triangulation, effectively extending the surface with a flange
            flange_point_count (int, default 11): the number of points to generate in the flange ring; ignored if
@@ -509,10 +731,12 @@ class Surface(rqsb.BaseSurface):
            make_clockwise (bool, default False): if True, the returned triangles will all be clockwise when
               viewed in the direction -ve to +ve z axis; if reorient is also True, the clockwise aspect is
               enforced in the reoriented space
+           normal_vector (triple float, optional): if present and reorienting, the normal vector to use for reorientation;
+              if None, the reorientation is made so as to minimise the z range
 
         returns:
            if extend_with_flange is True, numpy bool array with a value per triangle indicating flange triangles;
-           if extent_with_flange is False, None
+           if extend_with_flange is False, None
 
         notes:
            if extend_with_flange is True, then a boolean array is created for the surface, with a value per triangle,
@@ -520,23 +744,18 @@ class Surface(rqsb.BaseSurface):
            suitable for adding as a property for the surface, with indexable element 'faces';
            when flange extension occurs, the radius is the greater of the values determined from the radial factor
            and radial distance arguments;
-           the saucer_parameter is interpreted in one of two ways: (1) +ve fractoinal values between zero and one
-           are the fractional distance from the centre of the points to its rim at which to sample the surface for
-           extrapolation and thereby modify the recumbent z of flange points; 0 will usually give shallower and
-           smoother saucer; larger values (must be less than one) will lead to stronger and more erratic saucer
-           shape in flange; (2) other values between -90.0 and 90.0 are interpreted as an angle to apply out of
-           the plane of the original points, to give a simple (and less computationally demanding) saucer shape;
-           +ve angles result in the shift being in the direction of the -ve z hemisphere; -ve angles result in
-           the shift being in the +ve z hemisphere; in either case the direction of the shift is perpendicular
-           to the average plane of the original points
+           the saucer_parameter must be between -90.0 and 90.0, and is interpreted as an angle to apply out of
+           the plane of the original points, to give a simple saucer shape; +ve angles result in the shift being in 
+           the direction of the -ve z hemisphere; -ve angles result in the shift being in the +ve z hemisphere; in 
+           either case the direction of the shift is perpendicular to the average plane of the original points;
+           normal_vector, if supplied, should be in the crs of the point set
         """
 
         simple_saucer_angle = None
-        if saucer_parameter is not None and (saucer_parameter > 1.0 or saucer_parameter < 0.0):
+        if saucer_parameter is not None:
             assert -90.0 < saucer_parameter < 90.0, f'simple saucer angle parameter must be less than 90 degrees; too big: {saucer_parameter}'
             simple_saucer_angle = saucer_parameter
             saucer_parameter = None
-        assert saucer_parameter is None or 0.0 <= saucer_parameter < 1.0
         crs = rqc.Crs(self.model, uuid = point_set.crs_uuid)
         p = point_set.full_array_ref()
         assert p.ndim >= 2
@@ -549,37 +768,44 @@ class Surface(rqsb.BaseSurface):
                 f'removing {len(p) - np.count_nonzero(row_mask)} NaN points from point set {point_set.title} prior to surface triangulation'
             )
             p = p[row_mask, :]
-        if crs.xy_units == crs.z_units or not reorient:
+        if crs.xy_units == crs.z_units:
             unit_adjusted_p = p
         else:
             unit_adjusted_p = p.copy()
             wam.convert_lengths(unit_adjusted_p[:, 2], crs.z_units, crs.xy_units)
-        if reorient:
+            # note: normal vector should already be for a crs with common xy  & z units
+        # reorient the points to the fault normal vector
+        if normal_vector is None:
             p_xy, self.normal_vector, reorient_matrix = triangulate.reorient(unit_adjusted_p,
                                                                              max_dip = reorient_max_dip)
         else:
-            p_xy = unit_adjusted_p
+            assert len(normal_vector) == 3
+            self.normal_vector = np.array(normal_vector, dtype = np.float64)
+            if self.normal_vector[2] < 0.0:
+                self.normal_vector = -self.normal_vector
+            incl = vec.inclination(normal_vector)
+            if maths.isclose(incl, 0.0):
+                reorient_matrix = vec.no_rotation_matrix()
+                p_xy = unit_adjusted_p
+            else:
+                azi = vec.azimuth(normal_vector)
+                reorient_matrix = vec.tilt_3d_matrix(azi, incl)
+                p_xy = vec.rotate_array(reorient_matrix, unit_adjusted_p)
         if extend_with_flange:
-            if not reorient:
-                assert saucer_parameter is None and simple_saucer_angle is None,  \
-                    'flange saucer mode only available with reorientation active'
-                log.warning('extending point set with flange without reorientation')
-            flange_points = triangulate.surrounding_xy_ring(p_xy,
-                                                            count = flange_point_count,
-                                                            radial_factor = flange_radial_factor,
-                                                            radial_distance = flange_radial_distance,
-                                                            inner_ring = flange_inner_ring,
-                                                            saucer_angle = simple_saucer_angle)
-            p_xy_e = np.concatenate((p_xy, flange_points), axis = 0)
+            flange_points, radius = triangulate.surrounding_xy_ring(p_xy,
+                                                                    count = flange_point_count,
+                                                                    radial_factor = flange_radial_factor,
+                                                                    radial_distance = flange_radial_distance,
+                                                                    inner_ring = flange_inner_ring,
+                                                                    saucer_angle = 0.0)
+            flange_points_reverse_oriented = vec.rotate_array(reorient_matrix.T, flange_points)
             if reorient:
-                # reorient back extenstion points into original p space
-                flange_points_reverse_oriented = vec.rotate_array(reorient_matrix.T, flange_points)
-                p_e = np.concatenate((unit_adjusted_p, flange_points_reverse_oriented), axis = 0)
+                p_xy_e = np.concatenate((p_xy, flange_points), axis = 0)
             else:
-                p_e = p_xy_e
+                p_xy_e = np.concatenate((unit_adjusted_p, flange_points_reverse_oriented), axis = 0)
+
         else:
-            p_xy_e = p_xy
-            p_e = unit_adjusted_p
+            p_xy_e = unit_adjusted_p
             flange_array = None
         log.debug('number of points going into dt: ' + str(len(p_xy_e)))
         success = False
@@ -594,19 +820,214 @@ class Surface(rqsb.BaseSurface):
             t = triangulate.dt(p_xy_e[:, :2], container_size_factor = convexity_parameter * 1.1)
         log.debug('number of triangles: ' + str(len(t)))
         if make_clockwise:
-            triangulate.make_all_clockwise_xy(t, p_e)  # modifies t in situ
+            triangulate.make_all_clockwise_xy(t, p_xy_e)  # modifies t in situ
         if extend_with_flange:
             flange_array = np.zeros(len(t), dtype = bool)
             flange_array[:] = np.where(np.any(t >= len(p), axis = 1), True, False)
-            if saucer_parameter is not None:
-                _adjust_flange_z(self.model, self.crs_uuid, p_xy_e, len(p), t, flange_array, saucer_parameter)
-                p_e = vec.rotate_array(reorient_matrix.T, p_xy_e)
-        if crs.xy_units != crs.z_units and reorient:
-            wam.convert_lengths(p_e[:, 2], crs.xy_units, crs.z_units)
+            if simple_saucer_angle is not None:
+                assert abs(simple_saucer_angle) < 90.0
+                z_shift = radius * maths.tan(vec.radians_from_degrees(simple_saucer_angle))
+                flange_points[:, 2] -= z_shift
+                flange_points_reverse_oriented = vec.rotate_array(reorient_matrix.T, flange_points)
+            if crs.xy_units != crs.z_units:
+                wam.convert_lengths(flange_points_reverse_oriented[:, 2], crs.xy_units, crs.z_units)
+            p_e = np.concatenate((p, flange_points_reverse_oriented))
+        else:
+            p_e = p
         self.crs_uuid = point_set.crs_uuid
         self.set_from_triangles_and_points(t, p_e)
         return flange_array
 
+    def extend_surface_with_flange(self,
+                                   convexity_parameter = 5.0,
+                                   reorient = False,
+                                   reorient_max_dip = None,
+                                   flange_point_count = 11,
+                                   flange_radial_factor = 10.0,
+                                   flange_radial_distance = None,
+                                   flange_inner_ring = False,
+                                   saucer_parameter = None,
+                                   make_clockwise = False,
+                                   retriangulate = False,
+                                   normal_vector = None):
+        """Returns a new Surface object where the original surface has been extended with a flange with a Delaunay triangulation of points in a PointSet object.
+
+        arguments:
+            convexity_parameter (float, default 5.0): controls how likely the resulting triangulation is to be
+                convex; reduce to 1.0 to allow slightly more concavities; increase to 100.0 or more for very little
+                chance of even a slight concavity
+            reorient (bool, default False): if True, a copy of the points is made and reoriented to minimise the
+                z range (ie. z axis is approximate normal to plane of points), to enhace the triangulation; if
+                normal_vector is supplied that is used to determine the reorientation instead of minimising z
+            reorient_max_dip (float, optional): if present, the reorientation of perspective off vertical is
+                limited to this angle in degrees; ignored if normal_vector is specified
+            flange_point_count (int, default 11): the number of points to generate in the flange ring; ignored if
+                retriangulate is False
+            flange_radial_factor (float, default 10.0): distance of flange points from centre of points, as a
+                factor of the maximum radial distance of the points themselves; ignored if extend_with_flange is False
+            flange_radial_distance (float, optional): if present, the minimum absolute distance of flange points from
+                centre of points; units are those of the crs
+            flange_inner_ring (bool, default False): if True, an inner ring of points, with double flange point counr,
+                is created at a radius just outside that of the furthest flung original point; this improves
+                triangulation of the extended point set when the original has a non-convex hull. Ignored if retriangulate
+                is False
+            saucer_parameter (float, optional): if present, and extend_with_flange is True, then a parameter
+                controlling the shift of flange points in a perpendicular direction away from the fault plane;
+                see notes for how this parameter is interpreted
+            make_clockwise (bool, default False): if True, the returned triangles will all be clockwise when
+                viewed in the direction -ve to +ve z axis; if reorient is also True, the clockwise aspect is
+                enforced in the reoriented space
+            retriangulate (bool, default False): if True, the surface will be generated with a retriangulation of
+                the existing points. If False, the surface will be generated by adding flange points and triangles directly
+                from the original surface edges, and will no retriangulate the input surface. If False the surface must not
+                contain tears
+            normal_vector (triple float, optional): if present and reorienting, the normal vector to use for reorientation;
+                if None, the reorientation is made so as to minimise the z range
+
+        returns:
+            a new surface, and a boolean array of length N, where N is the number of triangles on the surface. This boolean
+            array is False on original triangle points, and True for extended flange triangles
+
+        notes:
+            a boolean array is created for the surface, with a value per triangle, set to False (zero) for non-flange
+            triangles and True (one) for flange triangles; this array is suitable for adding as a property for the
+            surface, with indexable element 'faces';
+            when flange extension occurs, the radius is the greater of the values determined from the radial factor
+            and radial distance arguments;
+            the saucer_parameter is interpreted in one of two ways: (1) +ve fractoinal values between zero and one
+            are the fractional distance from the centre of the points to its rim at which to sample the surface for
+            extrapolation and thereby modify the recumbent z of flange points; 0 will usually give shallower and
+            smoother saucer; larger values (must be less than one) will lead to stronger and more erratic saucer
+            shape in flange; (2) other values between -90.0 and 90.0 are interpreted as an angle to apply out of
+            the plane of the original points, to give a simple (and less computationally demanding) saucer shape;
+            +ve angles result in the shift being in the direction of the -ve z hemisphere; -ve angles result in
+            the shift being in the +ve z hemisphere; in either case the direction of the shift is perpendicular
+            to the average plane of the original points;
+            normal_vector, if supplied, should be in the crs of this surface
+        """
+        prev_t, prev_p = self.triangles_and_points()
+        point_set = rqs.PointSet(self.model, crs_uuid = self.crs_uuid, title = self.title, points_array = prev_p)
+        if retriangulate:
+            out_surf = Surface(self.model, crs_uuid = self.crs_uuid, title = self.title)
+            return out_surf, out_surf.set_from_point_set(point_set, convexity_parameter, reorient, reorient_max_dip,
+                                                         True, flange_point_count, flange_radial_factor,
+                                                         flange_radial_distance, flange_inner_ring, saucer_parameter,
+                                                         make_clockwise, normal_vector)
+        else:
+            simple_saucer_angle = None
+            if saucer_parameter is not None and (saucer_parameter > 1.0 or saucer_parameter < 0.0):
+                assert -90.0 < saucer_parameter < 90.0, f'simple saucer angle parameter must be less than 90 degrees; too big: {saucer_parameter}'
+                simple_saucer_angle = saucer_parameter
+                saucer_parameter = None
+            assert saucer_parameter is None or 0.0 <= saucer_parameter < 1.0
+            crs = rqc.Crs(self.model, uuid = point_set.crs_uuid)
+            assert prev_p.ndim >= 2
+            assert prev_p.shape[-1] == 3
+            p = prev_p.reshape((-1, 3))
+            if crs.xy_units == crs.z_units or not reorient:
+                unit_adjusted_p = p
+            else:
+                unit_adjusted_p = p.copy()
+                wam.convert_lengths(unit_adjusted_p[:, 2], crs.z_units, crs.xy_units)
+            if reorient:
+                p_xy, normal, reorient_matrix = triangulate.reorient(unit_adjusted_p, max_dip = reorient_max_dip)
+            else:
+                p_xy = unit_adjusted_p
+                normal = self.normal()
+                reorient_matrix = None
+
+            centre_point = np.nanmean(p_xy.reshape((-1, 3)), axis = 0)  # work out the radius for the flange points
+            p_radius_v = np.nanmax(np.abs(p.reshape((-1, 3)) - np.expand_dims(centre_point, axis = 0)), axis = 0)[:2]
+            p_radius = maths.sqrt(np.sum(p_radius_v * p_radius_v))
+            radius = p_radius * flange_radial_factor
+            if flange_radial_distance is not None and flange_radial_distance > radius:
+                radius = flange_radial_distance
+
+            de, dc = self.distinct_edges_and_counts()  # find the distinct edges and counts
+            unique_edge = de[dc == 1]  # find hull edges (edges on only a single triangle)
+            hull_points = p_xy[unique_edge]  # find points defining the hull edges
+            hull_centres = np.mean(hull_points, axis = 1)  # find the centre of each edge
+
+            flange_points = np.empty(
+                shape = (hull_centres.shape), dtype = float
+            )  # loop over all the hull centres, generating a flange point and finding the azimuth from the centre to the hull centre point
+            az = np.empty(shape = len(hull_centres), dtype = float)
+            for i, c in enumerate(hull_centres):
+                v = [centre_point[0] - c[0], centre_point[1] - c[1], centre_point[2] - c[2]]
+                uv = -vec.unit_vector(v)
+                az[i] = vec.azimuth(uv)
+                flange_point = centre_point + radius * uv
+                if simple_saucer_angle is not None:
+                    z_shift = radius * maths.tan(vec.radians_from_degrees(simple_saucer_angle))
+                    if reorient:
+                        flange_point[2] -= z_shift
+                    else:
+                        flange_point -= (-vec.unit_vector(normal) * z_shift)
+                flange_points[i] = flange_point
+
+            sort_az_ind = np.argsort(np.array(az))  # sort by azimuth, to run through the hull points
+            new_points = np.empty(shape = (len(flange_points), 3), dtype = float)
+            new_triangles = np.empty(shape = (len(flange_points) * 2, 3), dtype = int)
+            point_offset = len(p_xy)  # the indices of the new triangles will begin after this
+            for i, ind in enumerate(sort_az_ind):  # loop over each point in azimuth order
+                new_points[i] = flange_points[ind]
+                this_hull_edge = unique_edge[ind]
+
+                def az_for_point(c):
+                    v = [centre_point[0] - c[0], centre_point[1] - c[1], centre_point[2] - c[2]]
+                    uv = -vec.unit_vector(v)
+                    return vec.azimuth(uv)
+
+                this_edge_az_sort = np.array(
+                    [az_for_point(p_xy[this_hull_edge[0]]),
+                     az_for_point(p_xy[this_hull_edge[1]])])
+                if np.min(this_edge_az_sort) < az[ind] < np.max(this_edge_az_sort):
+                    first, second = np.argsort(this_edge_az_sort)
+                else:
+                    second, first = np.argsort(this_edge_az_sort)
+                if i != len(sort_az_ind) - 1:
+                    new_triangles[2 * i] = np.array(
+                        [this_hull_edge[first], this_hull_edge[second],
+                         i + point_offset])  # add a triangle between the two hull points and the flange point
+                    new_triangles[(2 * i) + 1] = np.array(
+                        [this_hull_edge[second], i + point_offset,
+                         i + point_offset + 1])  # for all but the last point, hookup triangle to the next flange point
+                else:
+                    new_triangles[2 * i] = np.array(
+                        [this_hull_edge[first], this_hull_edge[second],
+                         i + point_offset])  # add a triangle between the two hull points and the first flange point
+                    new_triangles[(2 * i) + 1] = np.array(
+                        [this_hull_edge[second], point_offset,
+                         i + point_offset])  # add in the final triangle between the first and last flange points
+
+            all_points = np.concatenate((p_xy, new_points))  # concatenate triangle and points arrays
+            all_triangles = np.concatenate((prev_t, new_triangles))
+
+            flange_array = np.zeros(shape = all_triangles.shape[0], dtype = bool)
+            flange_array[
+                len(prev_t):] = True  # make a flange bool array, where all new triangles are flange and therefore True
+
+            assert len(all_points) == (
+                point_offset + len(flange_points)), "New point count should be old point count + flange point count"
+            assert len(all_triangles) == (
+                len(prev_t) +
+                2 * len(flange_points)), "New triangle count should be old triangle count + 2 x #flange points"
+
+            if saucer_parameter is not None:
+                _adjust_flange_z(self.model, crs.uuid, all_points, len(all_points), all_triangles, flange_array,
+                                 saucer_parameter)  # adjust the flange points if in saucer mode
+            if reorient:
+                all_points = vec.rotate_array(reorient_matrix.T, all_points)
+            if crs.xy_units != crs.z_units and reorient:
+                wam.convert_lengths(all_points[:, 2], crs.xy_units, crs.z_units)
+
+            if make_clockwise:
+                triangulate.make_all_clockwise_xy(all_triangles, all_points)  # modifies t in situ
+
+            out_surf = Surface(self.model, crs_uuid = self.crs_uuid, title = self.title)
+            out_surf.set_from_triangles_and_points(all_triangles, all_points)  # create the new surface
+            return out_surf, flange_array
+
     def make_all_clockwise_xy(self, reorient = False):
         """Reorders cached triangles data such that all triangles are clockwise when viewed from -ve z axis.
 
@@ -629,7 +1050,7 @@ class Surface(rqsb.BaseSurface):
 
         _, p = self.triangles_and_points()
         crs = rqc.Crs(self.model, uuid = self.crs_uuid)
-        if crs.xy_units == self.z_units:
+        if crs.xy_units == crs.z_units:
             return p
         unit_adjusted_p = p.copy()
         wam.convert_lengths(unit_adjusted_p[:, 2], crs.z_units, crs.xy_units)
@@ -641,9 +1062,10 @@ class Surface(rqsb.BaseSurface):
         notes:
            the result becomes more meaningless the less planar the surface is;
            even for a parfectly planar surface, the result is approximate;
-           true normal vector is found when xy & z units differ
+           true normal vector is found when xy & z units differ, ie. for consistent units
         """
 
+        self._load_normal_vector_from_extra_metadata()
         if self.normal_vector is None:
             p = self.unit_adjusted_points()
             _, self.normal_vector, _ = triangulate.reorient(p)
@@ -746,7 +1168,7 @@ class Surface(rqsb.BaseSurface):
 
     def set_to_multi_cell_faces_from_corner_points(self, cp, quad_triangles = True):
         """Populates this (empty) surface to represent faces of a set of cells.
-        
+
         From corner points of shape (N, 2, 2, 2, 3).
         """
         assert cp.size % 24 == 0
@@ -782,7 +1204,7 @@ class Surface(rqsb.BaseSurface):
 
     def set_to_horizontal_plane(self, depth, box_xyz, border = 0.0, quad_triangles = False):
         """Populate this (empty) surface with a patch of two triangles.
-        
+
         Triangles define a flat, horizontal plane at a given depth.
 
         arguments:
@@ -850,7 +1272,7 @@ class Surface(rqsb.BaseSurface):
             v_index = None
             for line in lines:
                 if "VRTX" in line:
-                    words = line.rstrip().split(" ")
+                    words = line.rstrip().split()
                     v_i = int(words[1])
                     if v_index is None:
                         v_index = v_i
@@ -860,10 +1282,11 @@ class Surface(rqsb.BaseSurface):
                         v_index = v_i
                     vertices.append(words[2:5])
                 elif "TRGL" in line:
-                    triangles.append(line.rstrip().split(" ")[1:4])
+                    triangles.append(line.rstrip().split()[1:4])
         assert len(vertices) >= 3, 'vertices missing'
         assert len(triangles) > 0, 'triangles missing'
-        triangles = np.array(triangles, dtype = int) - index_offset
+        t_type = np.int32 if len(vertices) <= 2_147_483_647 else np.int64
+        triangles = np.array(triangles, dtype = t_type) - index_offset
         vertices = np.array(vertices, dtype = float)
         assert np.all(triangles >= 0) and np.all(triangles < len(vertices)), 'triangle vertex indices out of range'
         self.set_from_triangles_and_points(triangles = triangles, points = vertices)
@@ -885,7 +1308,7 @@ class Surface(rqsb.BaseSurface):
 
     def vertical_rescale_points(self, ref_depth = None, scaling_factor = 1.0):
         """Modify the z values of points by rescaling.
-        
+
         Stretches the distance from reference depth by scaling factor.
         """
         if scaling_factor == 1.0:
@@ -901,10 +1324,10 @@ class Surface(rqsb.BaseSurface):
         for patch in self.patch_list:
             patch.vertical_rescale_points(ref_depth, scaling_factor)
 
-    def line_intersection(self, line_p, line_v, line_segment = False):
+    def line_intersection(self, line_p, line_v, line_segment = False, patch = None):
         """Returns x,y,z of an intersection point of straight line with the surface, or None if no intersection found."""
 
-        t, p = self.triangles_and_points()
+        t, p = self.triangles_and_points(patch = patch)
         tp = p[t]
         intersects = meet.line_triangles_intersects(line_p, line_v, tp, line_segment = line_segment)
         indices = meet.intersects_indices(intersects)
@@ -912,21 +1335,22 @@ class Surface(rqsb.BaseSurface):
             return None
         return intersects[indices[0]]
 
-    def sample_z_at_xy_points(self, points, multiple_handling = 'any'):
+    def sample_z_at_xy_points(self, points, multiple_handling = 'any', patch = None):
         """Returns interpolated z values for an array of xy values.
 
         arguments:
             points (numpy float array of shape (..., 2 or 3)): xy points to sample surface at (z values ignored)
             multiple_handling (str, default 'any'): one of 'any', 'minimum', 'maximum', 'exception'
+            patch (int, optional): patch index; if None, results are for the full surface
 
         returns:
             numpy float array of shape points.shape[:-1] being z values interpolated from the surface z values
 
         notes:
             points must be in the same crs as the surface;
-            NaN will be set for any points that do not intersect with the surface in the xy projection;
-            multiple_handling argument controls behaviour when one sample point intersects surface more than
-            once: 'any' a random one of the intersection z values is returned; 'minimum' or 'maximum': the
+            NaN will be set for any points that do not intersect with the patch or surface in the xy projection;
+            multiple_handling argument controls behaviour when one sample point intersects more than once:
+            'any' a random one of the intersection z values is returned; 'minimum' or 'maximum': the
             numerical min or max of the z values is returned; 'exception': a ValueError is raised
         """
 
@@ -938,10 +1362,10 @@ class Surface(rqsb.BaseSurface):
         else:
             sample_xy = np.zeros((points.size // 2, 3), dtype = float)
             sample_xy[:, :2] = points.reshape((-1, 2))
-        t, p = self.triangles_and_points()
+        t, p = self.triangles_and_points(patch = patch)
         p_list = vec.points_in_triangles_njit(sample_xy, p[t], 1)
         vertical = np.array((0.0, 0.0, 1.0), dtype = float)
-        z = np.full(sample_xy.shape[0], np.NaN, dtype = float)
+        z = np.full(sample_xy.shape[0], np.nan, dtype = float)
         for triangle_index, p_index, _ in p_list:
             # todo: replace following with cheaper trilinear interpolation, given vertical intersection line
             xyz = meet.line_triangle_intersect_numba(sample_xy[p_index], vertical, p[t[triangle_index]], t_tol = 0.05)
@@ -957,17 +1381,18 @@ class Surface(rqsb.BaseSurface):
                 raise ValueError(f'multiple {self.title} surface intersections at xy: {sample_xy[p_index]}')
         return z.reshape(points.shape[:-1])
 
-    def normal_vectors(self, add_as_property: bool = False) -> np.ndarray:
-        """Returns the normal vectors for each triangle in the surface.
-        
+    def normal_vectors(self, add_as_property: bool = False, patch = None) -> np.ndarray:
+        """Returns the normal vectors for each triangle in the patch or surface.
+
         arguments:
-            add_as_property (bool): if True, face_surface_normal_vectors_array is added as a property to the model.
+            add_as_property (bool): if True, face_surface_normal_vectors_array is added as a property to the model
+            patch (int, optional): patch index; if None, normal vectors for triangles in all patches are returned
 
         returns:
-            normal_vectors_array (np.ndarray): the normal vectors corresponding to each triangle in the surface.
+            normal_vectors_array (np.ndarray): the normal vectors corresponding to each triangle in the surface
         """
         crs = rqc.Crs(self.model, uuid = self.crs_uuid)
-        triangles, points = self.triangles_and_points()
+        triangles, points = self.triangles_and_points(patch = patch)
         if crs.xy_units != crs.z_units:
             points = points.copy()
             wam.convert_lengths(points[:, 2], crs.z_units, crs.xy_units)
@@ -1027,13 +1452,13 @@ class Surface(rqsb.BaseSurface):
         return ep
 
     def resampled_surface(self, title = None):
-        """Creates a new triangulated set which is a resampled version of the current triangulated set. Each existing triangle in the tset is divided equally into 4 new triangles.
-           
+        """Creates a new surface which is a refined version of this surface; each triangle is divided equally into 4 new triangles.
+
         arguments:
-            title (str): a new title for the output triangulated set, if None the title will have the same title as the input triangulated set
-        
+            title (str): title for the output triangulated set, if None the title will be inherited from the input surface
+
         returns:
-            resqpy.surface.Surface object, with extra_metadata ('resampled from surface': <uuid>), where uuid is the origin surface uuid
+            resqpy.surface.Surface object, with extra_metadata ('resampled from surface': uuid), where uuid is for the original surface uuid
         """
         rt, rp = self.triangles_and_points()
         edge1 = np.mean(rp[rt[:]][:, ::2, :], axis = 1)
@@ -1050,8 +1475,9 @@ class Surface(rqsb.BaseSurface):
 
         # TODO: implement alternate solution using edge functions in olio triangulation to optimise
         points_unique, inverse = np.unique(allpoints, axis = 0, return_inverse = True)
-        tris = np.array(tris)
-        tris_unique = np.empty(shape = tris.shape)
+        t_type = np.int32 if len(allpoints) <= 2_147_483_647 else np.int64
+        tris = np.array(tris, dtype = t_type)
+        tris_unique = np.empty(shape = tris.shape, dtype = t_type)
         tris_unique[:, 0] = inverse[tris[:, 0]]
         tris_unique[:, 1] = inverse[tris[:, 1]]
         tris_unique[:, 2] = inverse[tris[:, 2]]
@@ -1066,6 +1492,37 @@ class Surface(rqsb.BaseSurface):
 
         return resampled
 
+    def resample_surface_unique_edges(self):
+        """Returns a new surface, with the same model, title and crs as the original, but with additional refined points along tears and edges.
+
+        Each edge forming a tear or outer edge in the surface will have 3 additional points added, with 2 additional points
+        on each edge of the original triangle. The output surface is re-triangulated using these new points (tears will be filled)
+
+        returns: 
+            new Surface object with extra_metadata ('unique edges resampled from surface': uuid), where uuid is for the original surface uuid
+            
+        note:
+            this method involves a tr-triangulation
+        """
+        _, op = self.triangles_and_points()
+        ref = self.resampled_surface()  # resample the original surface
+        rt, rp = ref.triangles_and_points()
+        de, dc = ref.distinct_edges_and_counts()  # find the distinct edges and counts for the resampled surface
+        de_edge = de[dc == 1]  # find edges that only appear once - tears or surface edges
+        edge_tri_index = np.sum(np.isin(rt, de_edge), axis = 1) == 2
+        edge_tris = rp[rt[edge_tri_index]]
+        mid = np.mean(rp[de_edge], axis = 1)  # get the midpoint of each surface edge
+        edge_ref_points = np.unique(np.concatenate([op, edge_tris.reshape(-1, 3), mid]), axis = 0)  # combine all points
+
+        points = rqs.PointSet(self.model, points_array = edge_ref_points, title = self.title,
+                              crs_uuid = self.crs_uuid)  # generate a pointset from these points
+
+        output = Surface(self.model, point_set = points,
+                         extra_metadata = {'resampled from surface': str(self.uuid)
+                                          })  # return a surface with generated from these points
+
+        return output
+
     def write_hdf5(self, file_name = None, mode = 'a'):
         """Create or append to an hdf5 file, writing datasets for the triangulated patches after caching arrays.
 
@@ -1115,7 +1572,13 @@ class Surface(rqsb.BaseSurface):
         if not self.title:
             self.title = 'surface'
 
-        tri_rep = super().create_xml(add_as_part = False, title = title, originator = originator)
+        em = None
+        if self.normal_vector is not None and (self.extra_metadata is None or
+                                               'normal vector' not in self.extra_metadata):
+            assert len(self.normal_vector) == 3
+            em = {'normal vector': f'{self.normal_vector[0]},{self.normal_vector[1]},{self.normal_vector[2]}'}
+
+        tri_rep = super().create_xml(add_as_part = False, title = title, originator = originator, extra_metadata = em)
 
         # todo: if crs_uuid is None, attempt to set to surface patch crs uuid (within patch loop, below)
         if crs_uuid is not None:
@@ -1221,6 +1684,16 @@ class Surface(rqsb.BaseSurface):
 
         return tri_rep
 
+    def _load_normal_vector_from_extra_metadata(self):
+        if self.normal_vector is None and self.extra_metadata is not None:
+            nv_str = self.extra_metadata.get('normal vector')
+            if nv_str is not None:
+                nv_words = nv_str.split(',')
+                assert len(nv_words) == 3, f'failed to convert normal vector string into triplet: {nv_str}'
+                self.normal_vector = np.empty(3, dtype = float)
+                for i in range(3):
+                    self.normal_vector[i] = float(nv_words[i])
+
 
 def distill_triangle_points(t, p):
     """Returns a (triangles, points) pair with points distilled as only those used from p."""
@@ -1229,7 +1702,8 @@ def distill_triangle_points(t, p):
     # find unique points used by triangles
     p_keep = np.unique(t)
     # note new point index for each old point that is being kept
-    p_map = np.full(len(p), -1, dtype = int)
+    t_type = np.int32 if len(p) <= 2_147_483_647 else np.int64
+    p_map = np.full(len(p), -1, dtype = t_type)
     p_map[p_keep] = np.arange(len(p_keep))
     # copy those unique points into a trimmed points array
     points_distilled = p[p_keep]
@@ -1256,8 +1730,9 @@ def nan_removed_triangles_and_points(t, p):
     expanded_mask[:] = np.expand_dims(np.logical_not(t_nan_mask), axis = -1)
     t_filtered = t[expanded_mask].reshape((-1, 3))
     # modified the filtered t values to adjust for the compression of filtered p
-    p_map = np.full(len(p), -1, dtype = int)
-    p_map[p_non_nan_mask] = np.arange(len(p_filtered), dtype = int)
+    t_type = np.int32 if len(p) <= 2_147_483_647 else np.int64
+    p_map = np.full(len(p), -1, dtype = t_type)
+    p_map[p_non_nan_mask] = np.arange(len(p_filtered), dtype = t_type)
     t_filtered = p_map[t_filtered]
     assert t_filtered.ndim == 2 and t_filtered.shape[1] == 3
     assert not np.any(t_filtered < 0) and not np.any(t_filtered >= len(p_filtered))