Read Amira surface (aka HxSurface or HyperSurface) files into hxsurf object

read.hxsurf(
  filename,
  RegionNames = NULL,
  RegionChoice = "both",
  FallbackRegionCol = "grey",
  Verbose = FALSE
)

Arguments

filename

Character vector defining path to file

RegionNames

Character vector specifying which regions should be read from file. Default value of NULL => all regions.

RegionChoice

Whether the Inner or Outer material, or both (default), should define the material of the patch. See details.

FallbackRegionCol

Colour to set regions when no colour is defined

Verbose

Print status messages during parsing when TRUE

Value

A list with S3 class hxsurf with elements

  • Vertices A data.frame with columns X, Y, Z, PointNo

  • Regions A list with 3 column data.frames specifying triplets of vertices for each region (with reference to PointNo column in Vertices element)

  • RegionList Character vector of region names (should match names of Regions element)

  • RegionColourList Character vector specifying default colour to plot each region in R's rgb format

Details

Note that when RegionChoice="both" or RegionChoice=c("Inner", "Outer") both polygons in inner and outer regions will be added to named regions. To understand the significance of this, consider two adjacent regions, A and B, with a shared surface. For the polygons in both A and B, Amira will have a patch with (say) InnerRegion A and OuterRegion B. This avoids duplication in the file. However, it might be convenient to add these polygons to both regions when we read them into R, so that regions A and B in our R object are both closed surfaces. To achieve this when RegionChoice="both", read.hxsurf adds these polygons to region B (as well as region A) but swaps the order of the vertices defining the polygon to ensure that the surface directionality is correct.

As a rule of thumb, stick with RegionChoice="both". If you get more regions than you wanted, then try switching to RegionChoice="Inner" or RegionChoice="Outer".

Note that the support for reading Amira's binary mesh format (HxSurface binary) is less mature and in particular only a few multi region mesh files have been tested. Finally there is no support to read meshes from the newer "Amira Binary Surface format" although such files can be read into a list using the read.amiramesh function.

Examples

if (FALSE) {
read.hxsurf("my.surf", RegionChoice="both")
}