Comma Separated Value (.csv)

司机简称

CSV

Driver built-in by default

This driver is built-in by default

OGR主要支持读取和写入存储在文本CSV文件中的非空间表格数据。CSV文件是支持表格数据的软件包之间的一种常见交换格式,也可以通过文本编辑器或最终用户编写的脚本或程序轻松地手动生成。

虽然理论上.csv文件可以有任何扩展名,但为了自动识别格式,OGR只支持以扩展名“.csv”结尾的csv文件。数据源名称可以是单个CSV文件,也可以指向目录。要将目录识别为.csv数据源,目录中至少一半的文件需要扩展名为.csv。从访问的每个.csv文件生成一个层(表)。

对于结构为CSV但扩展名不以.CSV结尾的文件,可以在文件名之前添加“CSV:”前缀,以强制CSV驱动程序加载。

OGR CSV驱动程序支持读写。因为CSV格式有可变长度的文本行,所以读取是按顺序进行的。按随机顺序阅读功能通常会非常慢。OGR CSV层可能有一个存储在.prj文件中的坐标系(请参见GeoCSV规范)。在读取名为“WKT”的字段时,假定该字段包含WKT几何图形,但也被视为常规字段。如果没有字段类型信息文件(扩展名为.csvt),则OGR CSV驱动程序将所有属性列作为字符串数据类型返回。

对于整数、实数、字符串、日期(YYYY-MM-DD)、时间(HH:MM:SS+nn)、日期时间(yyy-MM-DD HH:MM:SS+nn)列,可以通过与CSV文件同名但扩展名为.csvt的描述性文件进行有限的类型识别。在一行中,每列的类型必须用双引号列出,并用逗号分隔(例如,“整数”、“字符串”)。也可以明确指定每列的宽度和精度,例如“Integer(5)”、“Real(10.7)”、“String(15)”。然后驱动程序将使用为csv列指定的这些类型。子类型可以在括号之间传递,例如“Integer(Boolean)”、“Integer(Int16)”和“Real(Float32)”。从gdal2.1开始,相应地 GeoCSV specification ,可以使用“CoordX”或“Point(X)”类型指定具有经度/东距值的列,“CoordY”或“Point(Y)”表示纬度/北距值,以及“WKT”表示以WKT编码的几何图形

从GDAL 2.2开始,可以在.csvt中使用“JSonStringList”、“JSonIntegerList”、“JSonInteger64List”和“JSonRealList”类型映射到相应的OGR StringList、IntegerList、Integer64List和RealList类型。然后将字段值编码为JSon数组,并使用正确的CSV转义。

如果指定下面“打开选项”部分中描述的打开选项,也可以进行自动字段类型猜测。

驱动程序功能

Supports Create()

This driver supports the GDALDriver::Create() operation

Supports Georeferencing

This driver supports georeferencing

Supports VirtualIO

This driver supports virtual I/O operations (/vsimem/, etc.)

格式

CSV文件在层(表)中的每个特征(记录)有一行。属性字段值用逗号分隔。每行必须至少有两个字段。行可以由DOS(CR/LF)或Unix(LF)样式的行终止符终止。每条记录的字段数应相同。驱动程序还将接受分号、表格或空格字符作为字段分隔符。只有在CSV文件的第一行没有其他可能的分隔符时,此自动检测才会起作用。否则,它将默认使用逗号作为分隔符。

复杂属性值(例如包含逗号、引号或换行符的属性值)可以放在双引号中。引用字符串中出现的任何双引号都应加倍以“转义”它们。

默认情况下,驱动程序尝试将文件的第一行视为所有字段的字段名列表。但是,如果一个或多个名称都是数字,则假定第一行实际上是数据值,并在内部生成伪字段名(字段1到字段n),第一条记录被视为特征。如果数值用双引号括起来,则它们将被视为字段名。从gdal2.1开始,可以通过HEADERS open选项修改此行为。

所有CSV文件都被视为UTF-8编码。文件开头的字节顺序标记(BOM)将被正确解析。WRITEu BOM选项可用于创建带有字节顺序标记的文件,这可以提高与某些软件(特别是Excel)的兼容性。

示例(employee.csv):

ID,Salary,Name,Comments
132,55000.0,John Walker,"The ""big"" cheese."
133,11000.0,Jane Lake,Cleaning Staff

请注意,第一个数据记录的Comments值被放在双引号中,因为该值包含引号,并且这些引号必须被加倍,这样我们知道我们还没有到达引号字符串的末尾。

文本输入的许多变体有时称为逗号分隔值文件,包括不带逗号但固定列宽的文件、使用制表符作为分隔符的文件或具有定义字段类型或结构的其他辅助数据的文件。此驱动程序不尝试支持所有此类文件,而是支持可自动识别的简单.csv文件。脚本或其他机制通常可用于将其他变体转换为与OGR CSV驱动程序兼容的表单。

读取包含空间信息的CSV

建筑点几何图形

考虑以下CSV文件(test.CSV):

Latitude,Longitude,Name
48.1,0.25,"First point"
49.2,1.1,"Second point"
47.5,0.75,"Third point"

从GDAL 2.1开始,可以直接指定可能包含X/经度和Y/纬度的列的潜在名称,并使用X_-possible_names和Y_-possible_names open选项。

*ogrinfo -ro -al test.csv -oo X_POSSIBLE_NAMES=Lon* -oo Y_POSSIBLE_NAMES=纬度 * -oo KEEP_GEOM_COLUMNS=否*将返回:

OGRFeature(test):1
  Name (String) = First point
  POINT (0.25 48.1)

OGRFeature(test):2
  Name (String) = Second point
  POINT (1.1 49.2)

OGRFeature(test):3
  Name (String) = Third point
  POINT (0.75 47.5)

If CSV file does not have a header line, the dummy "field_n" names can be used as possible names for coordinate fields. For example plain XYZ point data can be opened as

ogrinfo -ro -al elevation.xyz -oo X_POSSIBLE_NAMES=field_1 -oo Y_POSSIBLE_NAMES=field_2 -oo Z_POSSIBLE_NAMES=field_3

否则,如果一个或多个列包含编码为WKT、WKB(十六进制编码)或GeoJSON的几何定义(在这种情况下,GeoJSON内容的格式必须遵循CSV规则,即必须用双引号括起来,并且字符串中的双引号必须重复才能正确转义),此类列的名称GEOM_POSSIBLE_name s open选项。

对于旧版本,可以通过使用 VRT 驱动程序。

您可以编写关联的VRT文件(test.VRT):

<OGRVRTDataSource>
    <OGRVRTLayer name="test">
        <SrcDataSource>test.csv</SrcDataSource>
        <GeometryType>wkbPoint</GeometryType>
        <LayerSRS>WGS84</LayerSRS>
        <GeometryField encoding="PointFromColumns" x="Longitude" y="Latitude"/>
    </OGRVRTLayer>
</OGRVRTDataSource>

ogrinfo -ro -al test.vrt 将返回:

OGRFeature(test):1
  Latitude (String) = 48.1
  Longitude (String) = 0.25
  Name (String) = First point
  POINT (0.25 48.1 0)

OGRFeature(test):2
  Latitude (String) = 49.2
  Longitude (String) = 1.1
  Name (String) = Second point
  POINT (1.1 49.200000000000003 0)

OGRFeature(test):3
  Latitude (String) = 47.5
  Longitude (String) = 0.75
  Name (String) = Third point
  POINT (0.75 47.5 0)

建筑线条几何

考虑以下CSV文件(test.CSV):

way_id,pt_id,x,y
1,1,2,49
1,2,3,50
2,1,-2,49
2,2,-3,50

启用了Spatialite的GDAL构建, ogrinfo test.csv -dialect SQLite -sql "SELECT way_id, MakeLine(MakePoint(CAST(x AS float),CAST(y AS float))) FROM test GROUP BY way_id" 将返回:

OGRFeature(SELECT):0
  way_id (String) = 1
  LINESTRING (2 49,3 50)

OGRFeature(SELECT):1
  way_id (String) = 2
  LINESTRING (-2 49,-3 50)

VSI虚拟文件系统API支持

驱动程序支持读取和写入由VSI虚拟文件系统API管理的文件,这些文件包括“常规”文件以及/vsizip/(读写)、/vsigzip/(只读)、/vsicurl/(只读)域中的文件。

还支持写入/dev/stdout或/vsistdout/。

打开选项

可以指定以下打开选项(通常使用ogrinfo或ogr2ogr的-oo name=value参数):

  • MERGE_SEPARATOR =是/否(默认为否)。将其设置为“是”将启用合并连续分隔符。当它是空间字符时最有用。

  • AUTODETECT_TYPE =是/否(默认为否)。设置为“是”将启用字段数据类型的自动检测。如果在读取记录(超出用于自动检测的记录)时,发现一个值与自动检测的数据类型不对应,则将发出警告并清空该字段。

  • KEEP_SOURCE_COLUMNS =YES/NO(默认为NO)保留猜测活动的原始列的副本,猜测的类型与string不同。原始列的名称将以“_original”作为后缀。只有当自动检测类型=是时,才应使用此标志。

  • AUTODETECT_WIDTH =YES/NO/STRING_ONLY(默认为NO)。设置为“是”可检测字符串和整数字段的宽度以及实数字段的宽度和精度。将其设置为STRING_仅限于STRING字段。将其设置为“否”选择默认大小和宽度。如果在读取记录(超出用于自动检测的记录)时,发现一个值与自动检测的宽度/精度不对应,则会发出警告并清空该字段。

  • AUTODETECT_SIZE_LIMIT =size,指定要检查的字节数,以确定数据类型和宽度/精度。默认值为100000。设置0意味着检查整个文件。注意:指定大于1 MB的值(如果文件大于1 MB,则为0)将阻止从标准输入进行读取。

  • QUOTED_FIELDS_AS_STRING =是/否(默认为否)。仅在“自动检测”类型为“是”时使用。当设置为“是”时,是否将带引号的字段强制为字符串字段。否则,默认情况下,将对引用字段的内容进行实数、整数等测试。。。数据类型。

  • X_POSSIBLE_NAMES =列出姓名。(GDAL>=2.1)点的X/经度坐标的可能名称的逗号分隔列表。每个名称都可以是在起始和/或结束位置使用星字符的模式。E、 g.:前缀 , * 后缀或 * 中间。列中的值必须是浮点值。必须同时指定X_-POSSIBLE_NAMES和Y_-POSSIBLE_NAMES,并且必须在CSV文件的列中找到每个名称的匹配项。当使用X_-POSSIBLE_NAMES/Y_-POSSIBLE_NAMES时,每层只能生成一个几何列。

  • Y_POSSIBLE_NAMES =列出姓名。(GDAL>=2.1)点的Y/纬度坐标的可能名称的逗号分隔列表。每个名称都可以是在起始和/或结束位置使用星字符的模式。E、 g.:前缀 , * 后缀或 * 中间。列中的值必须是浮点值。必须同时指定X_-POSSIBLE_NAMES和Y_-POSSIBLE_NAMES,并且必须在CSV文件的列中找到每个名称的匹配项。

  • Z_POSSIBLE_NAMES =列出姓名。(GDAL>=2.1)点的Z/高程坐标的可能名称的逗号分隔列表。每个名称都可以是在起始和/或结束位置使用星字符的模式。E、 g.:前缀 , * 后缀或 * 中间。列中的值必须是浮点值。仅与X_可能的名称和Y_可能的名称一起考虑。

  • GEOM_POSSIBLE_NAMES =列出姓名。(GDAL>=2.1)包含编码为WKT、WKB(十六进制形式,可能在PostGIS 2.0扩展WKB中)或GeoJSON的几何定义的几何列的可能名称的逗号分隔列表。每个名称都可以是在起始和/或结束位置使用星字符的模式。E、 g.:前缀 *, * 后缀或 * 中间的 *

  • KEEP_GEOM_COLUMNS =YES/NO(默认为YES)将检测到的X、Y、Z或geometry列公开为常规属性字段。

  • HEADERS =是/否/自动(默认自动)(GDAL>=2.1)文件的第一行是否包含列名。当设置为AUTO时,如果没有严格的数值,GDAL将假定第一行是列名。

  • EMPTY_STRING_AS_NULL =是/否(默认为否)(GDAL>=2.1)读取时是否将空字符串视为空字段。

创建问题

驱动程序支持创建新数据库(作为.csv文件的目录)、将新的.csv文件添加到现有目录或.csv文件或将功能附加到现有.csv表。从GDAL 2.1开始,支持删除或替换现有功能,或添加/修改/删除字段,前提是所做的修改足够小,可以在刷新到磁盘之前临时存储在RAM中。

Layer Creation options

  • LINEFORMAT :默认情况下,当创建新的.csv文件时,它们是使用本地平台的行终止约定创建的(在win32上为CR/LF,在所有其他系统上为LF)。这可以通过使用LINEFORMAT图层创建选项来覆盖,该选项的值可以为 CRLF (DOS格式)或 LF (Unix格式)。

  • GEOMETRY :默认情况下,将丢弃写入.csv文件的要素的几何图形。通过指定几何图形,可以导出WKT表示形式中的几何图形=AS_WKT . 还可以通过指定几何图形将点几何图形导出到其X、Y、Z组件(csv文件中的不同列)中=AS_XYZ ,几何图形=AS_XY 或几何学=AS_YX . 几何体列将被前置到具有属性值的列。也可以使用SQLite SQL方言查询导出GeoJSON表示中的几何图形,请参见下面的示例。

  • CREATE_CSVT =YES/NO:创建相关的.csvt文件(见上一段)来描述层的每一列的类型及其可选宽度和精度。默认值:否

  • SEPARATOR =逗号/分号/制表符/空格:字段分隔符。默认值:逗号

  • WRITE_BOM =是/否:在文件开头写入UTF-8字节顺序标记(BOM)。默认值:否

  • GEOMETRY_NAME =name(以GDAL 2.1开头):几何列的名称。仅当GEOMETRY=AS WKT且CREATE=YES时使用。默认为WKT

  • STRING_QUOTING =IF_NEEDED/IF_暧昧/ALWAYS(从GDAL 2.3开始):是否双引号字符串。IF含糊不清意味着看起来像数字的字符串值将被引用(这也意味着如果需要)。默认为IFu不明确(旧版本中的行为是IFu需要)

配置选项

The following configuration options are available:

  • OGR_WKT_PRECISION =int: Number of decimals for coordinate values. Default to 15. A heuristics is used to remove insignificant trailing 00000x or 99999x that can appear when formatting decimal numbers.

  • OGR_WKT_ROUND =YES/NO: (GDAL >= 2.3) Whether to enable the above mentioned heuristics to remove insignificant trailing 00000x or 99999x. Default to YES.

实例

  • 此示例显示如何使用ogr2ogr将具有点几何图形的shapefile转换为.csv文件,并将点的X、Y、Z坐标作为.csv文件中的第一列

    ogr2ogr -f CSV output.csv input.shp -lco GEOMETRY=AS_XYZ
    
  • 此示例显示如何使用ogr2ogr将shapefile转换为.csv文件,其中geography字段使用GeoJSON格式格式化。

    ogr2ogr -f CSV -dialect sqlite -sql "select AsGeoJSON(geometry) AS geom, * from input" output.csv input.shp
    
  • 将CSV转换为GeoPackage。指定坐标列的名称并指定坐标参照系。

    ogr2ogr \
      -f GPKG output.gpkg \
      input.csv \
      -oo X_POSSIBLE_NAMES=longitude \
      -oo Y_POSSIBLE_NAMES=latitude \
      -a_srs 'EPSG:4326'
    

特定数据源

CSV驱动程序还可以读取其结构接近CSV文件的文件:

其他音符