[[TOC]]
= OGR data provider in GRASS 7 =

See also [http://grass.osgeo.org/programming7/vlibOgr.html programmer's manual page] and user-oriented [http://grass.osgeo.org/wiki/Working_with_external_data_in_GRASS_7#Vector_data wiki page] on GRASS [http://grass.osgeo.org/wiki Wiki].
== Direct OGR read access ==

Capability to read OGR layers '''directly''' without linking them via {{{v.external}}}.

'''Example 1:''' Shapefile 'busstopsall.shp' located in directory '~/shapefiles'

{{{
v.info map=~/shapefiles/@OGR layer=busstopsall
}}}

'''Example 2:''' PostGIS table 'busstopsall' located in database 'pgis_nc'.

{{{
v.extract input=PG:dbname=pgis_nc@OGR layer=busstopsall where="STREET_1 = 'William Moore Dr.'" output=b1
}}}

List of modules which supports direct OGR read access ((*) indicates work in progress):

 * {{{v.info}}} (r39161), {{{v.db.connect}}} (r39538), {{{v.extract}}} (r39621), {{{v.db.select}}} (r39556), {{{v.buffer}}} (r39809), {{{v.category}}} (r39812), {{{v.class}}} (r39813), {{{v.clean}}} (r39814), {{{v.delaunay}}} (r39821), {{{v.dissolve}}} (r39822), {{{v.distance}}} (r39823), {{{v.drape}}} (r39826), {{{v.extrude}}} (r39827), {{{v.generalize}}} (r39828), {{{v.hull}}} (r39829), {{{v.kcv}}} (r39832), {{{v.neighbors}}} (r39834), {{{v.normal}}} (r39839), {{{v.out.ascii}}} (r39881), {{{v.out.dxf}}} (r39882), {{{v.out.ogr}}} (r39883), {{{v.out.pov}}} (r39884), {{{v.out.svg}}} (r39885), {{{v.overlay}}} (r39895), {{{v.parallel}}} (r39896), {{{v.pertrub}}} (r39897), {{{v.qcount}}} (r39898), {{{v.report}}} (r39905), {{{v.sample}}} (r39906), {{{v.segment}}} (r39907), {{{v.reclass}}} (r39908), {{{v.random}}} (r39909), {{{v.rast.stats}}} (r39910), {{{v.split}}}, {{{v.surf.idw}}}, {{{v.surf.rst}}}, {{{v.to.3d}}}, {{{v.to.db}}}, {{{v.to.points}}}, {{{v.to.rast}}}, {{{v.to.rast3}}}, {{{v.transform}}}, {{{v.type}}}, {{{v.univar}}}, {{{v.what}}} (r40188), {{{v.select}}} (r48936)

Source code: [source:grass/trunk/lib/vector/Vlib/read_ogr.c read_ogr.c]

'''Status:''' Currently all modules in GRASS 7 should support direct OGR read access.
== Direct OGR write access ==

Capability to write OGR layers directly without need to store data in the native GRASS vector format and then exporting data using {{{v.out.ogr}}}.

Testcase:

 * GRASS location: {{{nc_spm_08}}} - http://grass.osgeo.org/sampledata/nc_spm_latest.tar.gz
 * Shapefile directory: {{{~/shapefiles}}} - http://grass.osgeo.org/sampledata/north_carolina/nc_shape.tar.gz
 * PostGIS database: {{{pgis_nc}}} (see how to [http://www.youtube.com/watch?v=DTMmmcVpJKk export GRASS data to PostGIS] using [http://grass.osgeo.org/wiki/WxGUI_Modeler wxGUI Modeler])
=== ~~Scenario 1 (not implemented)~~ ===

Use parameters {{{output}}} for output OGR datasource and {{{olayer}}} for OGR layer. Example:

{{{
# input: GRASS data
# output: PostGIS database
v.extract input=bridges where="BRIDGE_NUM=417" output=bridges_417

# input: PostGIS layer, ESRI Shapefile
# output: PostGIS database
v.select ainput=PG:dbname=gisdb@OGR alayer=zeleznice \
 binput=shps@OGR blayer=obce operator=intersects \
 output=PG:dbname=gisdb@OGR olayer=obce_zelez
}}}

'''Status:''' not planned to be implemented
=== Scenario 2 (implemented) ===

Design `v.external.out` (similarly to `r.external.out`)

{{{
# input: GRASS data
# output: PostGIS database
v.external.out dsn=PG:dbname=pgis_nc format=PostgreSQL
v.extract input=bridges where="BRIDGE_NUM=417" output=bridges_417

# input: PostGIS layer, ESRI Shapefile
# output: PostGIS database
v.select ainput=PG:dbname=pgis_nc@OGR alayer=roadsmajor \
 binput=~/shapefiles@OGR blayer=boundary_municp operator=intersects \
 output=municp_roads
}}}

'''Status:''' implemented [source:grass/trunk/vector/v.external.out]. Only limited number of modules in GRASS 7 (those which writes data in simple-features-like form) allows to write output vector data directly using OGR library. 
=== Tasks ===

 * Attribute table (write) access for OGR-linked vectors (direct or linked by v.external)
  * Implemented in r47225
=== Changes in vector library ===

Source code: [source:grass/trunk/lib/vector/Vlib/write_ogr.c write_ogr.c]

 * New functions
  * `V1_write_line_ogr()`, `V2_write_line_ogr()`
  * `V1_rewrite_line_ogr()`, `V2_rewrite_line_ogr()`
  * `V1_delete_line_ogr()`, `V2_delete_line_ogr()`
 * `Vect_build_ogr()` support all build levels  - r48960
 * Implement `V2__add_line_to_topo_ogr()` - r49178
== Supported GRASS modules ==

=== Current status ===

|| '''Module''' || '''Read access (link)''' || '''Direct read access''' || '''Direct write access'''
|| `v.build`          || Y || N || N
|| `v.build.all`      || Y || N || N
|| `v.clean`          || Y || Y || N
|| `v.edit`           || Y || Y || Y
|| `v.extract`        || Y || Y || Y
|| `v.out.dxf`        || Y || Y || N
|| `v.select`         || Y || Y || Y
|| `v.random`         || Y || Y || Y
|| `v.voronoi`        || Y || Y || N
|| `v.what`           || Y || Y	|| X
|| `v.what.rast`      || Y || Y || Y
|| `v.what.vect`      || Y || Y || Y

=== Optimalization ===

Most of GRASS modules are designed to access features randomly which is basically quick for GRASS native vector data, but ''very very slow'' when accessing features via OGR library, see example bellow

{{{
#!cpp
    nlines = Vect_get_num_lines(&In);
    for (line = 1; line <= nlines; line++) {
	Vect_read_line(&In, Points, Cats, line);
    }
}}}

 * Test for vector map with 100.000 points

Native 

{{{
real    0m0.194s
user    0m0.164s
sys     0m0.024s
}}}

OGR-link 

{{{
real    0m35.616s
user    0m7.880s
sys     0m3.700s
}}}

Rewriting the code to use sequential access causes significant speed-up for OGR-links:

{{{
#!cpp
    while(TRUE) {
	if (Vect_read_next_line(&In, Points, Cats) == -2)
	    break;
    }
}}}

OGR-link
{{{
real    0m0.831s
user    0m0.444s
sys     0m0.016s
}}}

'''Simple test of rendering speed'''

See r47875

 * vector map 'bridges' (`points=10938`)

{{{d.vect bridges type=point}}}

Native:

{{{
real    0m0.400s
user    0m0.388s
sys     0m0.008s
}}}

Linked PostGIS layer:

{{{
real    0m0.828s
user    0m0.568s
sys     0m0.016s
}}}

(before r47875)

{{{
real    0m5.850s
user    0m1.860s
sys     0m0.464s
}}}

 * vector map 'roadsmajor' (`lines=355`)

{{{d.vect roadsmajor type=line}}}

Native:

{{{
real    0m0.103s
user    0m0.092s
sys     0m0.008s
}}}

Linked PostGIS layer:

{{{
real    0m0.521s
user    0m0.128s
sys     0m0.028s
}}}

 * vector map 'urbanarea' (`areas=666`)

{{{d.vect urbanarea type=centroid,area}}}

Native:

{{{
real    0m0.540s
user    0m0.520s
sys     0m0.016s
}}}

Linked PostGIS layer:

{{{
real    0m1.236s
user    0m0.736s
sys     0m0.068s
}}}

== Related OGR tickets ==

 * [http://trac.osgeo.org/gdal/ticket/4202 #4202]
 * [http://trac.osgeo.org/gdal/ticket/4217 #4217]