geofileops.copy_layer#

Copy a layer from a source to a destination dataset.

Typical use cases:

convert a file from one fileformat to another

reproject a layer to another spatial reference

export a subset of a layer using the where or sql_stmt parameter

add a layer to an existing file as a new layer (write_mode=”add_layer”)

append a layer to an existing layer (write_mode=”append”)

If an sql_stmt is specified, the sqlite query can contain following placeholders that will be automatically replaced for you:

{geometrycolumn}: the column where the primary geometry is stored.

{columns_to_select_str}: if ‘columns’ is not None, those columns, otherwise all columns of the layer.

{input_layer}: the layer name of the input layer.

Example SQL statement with placeholders:

SELECT {geometrycolumn}
      {columns_to_select_str}
  FROM "{input_layer}" layer

The options parameter can be used to pass any type of options to GDAL in the following form:

{ “<option_type>.<option_name>”: <option_value> }

The option types can be any of the following:

LAYER_CREATION: layer creation option (lco)

DATASET_CREATION: dataset creation option (dsco)

INPUT_OPEN: input dataset open option (oo)

DESTINATION_OPEN: destination dataset open option (doo)

CONFIG: config option (config)

The options can be found in the GDAL vector driver documentation.

Parameters:

src (PathLike) – The source path. GDAL vsi paths are also supported.
dst (PathLike) – The destination path. GDAL vsi paths can be used for handlers with write support.
src_layer (str, optional) – The source layer. If the source contains a single layer, that layer will be taken if src_layer is None. If it contains multiple layers, src_layer is mandatory unless sql_stmt is specified. Defaults to None.
dst_layer (str, optional) – The destination layer. If None, the destination file stem is taken as layer name. Defaults to None.
write_mode (str, optional) –
The write mode. Defaults to “create”. Valid values:
- ”create”: create a new destination file. If the file already exists
  and force=True the function just returns, if force=False the file is overwritten.
- ”add_layer”: add the source layer to the destination file as a new
  layer. When using “add_layer”, dst_layer should be specified. If the layer already exists and force=True the function just returns, if force=False the layer is overwritten.
- ”append”: append the source layer to the destination layer, if the
  layer already exists. If not, the file and/or layer will be created. If the file already contains layers named differently than the default layer name for the file, dst_layer becomes mandatory.
- ”append_add_fields”: append the source layer to the destination layer,
  adding fields from the source layer that are not present in the destination layer. If the layer doesn’t exist, it will be created. If the file already contains layers named differently than the default layer name for the file, dst_layer becomes mandatory.
Added in version 0.10.0.

Changed in version 0.11.0: Added “append_add_fields” write mode.
src_crs (Union[str, int], optional) – an epsg int or anything supported by the OGRSpatialReference.SetFromUserInput() call, which includes an EPSG string (eg. “EPSG:4326”), a well known text (WKT) CRS definition,… Defaults to None.
dst_crs (Union[str, int], optional) – an epsg int or anything supported by the OGRSpatialReference.SetFromUserInput() call, which includes an EPSG string (eg. “EPSG:4326”), a well known text (WKT) CRS definition,… Defaults to None.
columns (Iterable[str], optional) – The (non-geometry) columns to read will be returned in the order specified. If None, all standard columns are read. In addition to standard columns, it is also possible to specify “fid”, a unique index available in all input files. Note that the “fid” will be aliased eg. to “fid_1”. Defaults to None.
where (str, optional) – only append the rows from src that comply to the filter specified. Applied before explodecollections. Filter should be in sqlite SQL WHERE syntax and spatialite reference functions can be used. If where contains the {geometrycolumn} placeholder, it is filled out with the geometry column name of the src file. Defaults to None.
sql_stmt (str) – SQL statement to use. Only supported with “pyogrio” engine.
sql_dialect (str, optional) – SQL dialect used. Options are None, “SQLITE” or “OGRSQL”. If None, for data sources with explicit SQL support the statement is processed by the default SQL engine (e.g. for Geopackage and Spatialite this is “SQLITE”). For data sources without native SQL support (e.g. .shp), the “OGRSQL” dialect is the default. If the “SQLITE” dialect is specified, spatialite reference functions can also be used. Defaults to None.
reproject (bool, optional) – True to reproject while converting the file. Defaults to False.
explodecollections (bool, optional) – True to output only simple geometries. Defaults to False.
force_output_geometrytype (Union[GeometryType, str], optional) – Geometry type. to (try to) force the output to. In addition to geometry types, it is also possible to specify PROMOTE_TO_MULTI to convert all geometries to multigeometries or CONVERT_TO_LINEAR to convert CURVE geometries to linear. Defaults to None.
create_spatial_index (bool, optional) – True to create a spatial index on the destination file/layer. If None, the default behaviour by gdal for that file type is respected. If the LAYER_CREATION.SPATIAL_INDEX parameter is specified in options, create_spatial_index is ignored. Defaults to None.
transaction_size (int, optional) – Transaction size. Defaults to 50000.
preserve_fid (bool, optional) – True to make an extra effort to preserve fid’s of the source layer to the destination layer. False not to do any effort. None to use the default behaviour of gdal, that already preserves in some cases. Some file formats don’t explicitly store the fid (e.g. shapefile), so they will never be able to preserve fids. Defaults to None.
dst_dimensions (str, optional) – Force the dimensions of the destination layer to the value specified. Valid values: “XY”, “XYZ”, “XYM” or “XYZM”. Defaults to None.
options (dict, optional) – options to pass to gdal. Defaults to None.
append (bool, optional) –
True to append to the destination layer if it already exists. Defaults to False.

Deprecated since version 0.10.0: Please use write_mode=”append” instead.
force (bool, optional) – True to overwrite the output file/layer (depending on write_mode) if it already exists. False to just return if the output file/layer exists. Defaults to False.