IFC (version 0.1.1)

ExportToXIF: RIF/CIF File Writer

Description

Subsets or merges RIF or CIF files.

Usage

ExportToXIF(
  fileName,
  write_to,
  objects,
  offsets,
  fast = TRUE,
  extract_features = FALSE,
  endianness = .Platform$endian,
  verbose = FALSE,
  verbosity = 1,
  overwrite = FALSE,
  display_progress = TRUE,
  ...
)

Arguments

fileName

path(s) of file(s) to subset or merge. If multiple files are provided they will be merged. Otherwise, if only one file is input it will be subsetted. All files have to be either '.rif' or '.cif' files. All files should have same channels.

write_to

pattern used to export file. Placeholders, like "%d/%s_fromR.%e", will be substituted: -%d: with full path directory of first element of 'fileName' -%p: with first parent directory of first element of 'fileName' -%e: with extension of first element of 'fileName' (without leading .) -%s: with shortname from of first element of 'fileName' (i.e. basename without extension). Exported file extension will be deduced from this pattern. It has to be the same as 'fileName', i.e. .cif or .rif.

objects

integer vector, IDEAS objects ids numbers to use. If missing, the default, all objects will be used. Only apply for subsetting.

offsets

object of class `IFC_offset`. If missing, the default, offsets will be extracted from 'fileName'. This param is not mandatory but it may allow to save time for repeated XIF export on same file. Only apply for subsetting.

fast

whether to fast extract 'objects' or not. Default is TRUE. Meaning that 'objects' will be extracting expecting that objects are stored in ascending order. Note that a warning will be sent if an 'object' is found at an unexpected order. In such a case you may need to rerun function with 'fast' = FALSE. If set to FALSE, all object_ids will be scanned from 'fileName' to ensure extraction of desired 'objects'. IMPORTANT: whatever this argument is, features are extracted assuming an ascending order of storage in file. Only apply for subsetting.

extract_features

whether to try to extract features. Default is FALSE. IMPORTANT: it is not clear if how features are stored and which objects they rely to when input file is already a merge or a subset. For this reason it should be carefully checked. Note that features extraction is not implemented for merging.

endianness

the endian-ness ("big" or "little") of the target system for the file. Default is .Platform$endian. Endianness describes the bytes order of data stored within the files. This parameter may not be modified.

verbose

whether to display information (use for debugging purpose). Default is FALSE.

verbosity

quantity of information displayed when verbose is TRUE; 1: normal, 2: rich. Default is 1.

overwrite

whether to overwrite file or not. Default is FALSE. Note that if TRUE, it will overwrite exported file if path(s) of file(s) in 'fileName' and deduced from 'write_to' arguments are different. Otherwise, you will get an error saying that overwritting source file is not allowed. Note also that an original file, i.e. generated by IDEAS(R) or INSPIRE(R), will never be overwritten. Otherwise, you will get an error saying that overwritting original file is not allowed.

display_progress

whether to display a progress bar. Default is TRUE.

...

other arguments to be passed.

Value

It invisibly returns full path of exported file.

Details

when 'extract_features' is set TRUE, only features stored in binary format will be extracted if found. If the input 'fileName' is a merged of several files then features will be extracted from these files. If these files can't be found, Warning(s) will be thrown and input 'fileName' will be extracted without features values.

Examples

# NOT RUN {
if(requireNamespace("IFCdata", quietly = TRUE)) {
  tmp <- tempdir(check = TRUE)
  ## use a cif file, but you can also subset rif
  file_cif <- system.file("extdata", "example.cif", package = "IFCdata")
  ## subset objects 0,1 and 4 from file
  exported <- ExportToXIF(fileName = file_cif, write_to = paste0(tmp, "\\test.cif"),
                          overwrite = TRUE, objects = c(0,1,4))
} else {
  message(sprintf('Please run `install.packages("IFCdata", repos = "%s", type = "source")` %s',
                  'https://gitdemont.github.io/IFCdata/',
                  'to install extra files required to run this example.'))
}
# }