/ 
Geo-LibProj-FFI-0.03
River stage zero No dependents
/ Geo::LibProj::FFI

NAME

Geo::LibProj::FFI - Foreign function interface to PROJ coordinate transformation software

VERSION

version 0.03

SYNOPSIS

use Geo::LibProj::FFI qw(:all);
use Syntax::Keyword::Defer;

my $ctx = proj_context_create()
    or die "Cannot create threading context";
defer { proj_context_destroy($ctx); }

my $pj = proj_create_crs_to_crs($ctx, "EPSG:25833", "EPSG:2198", undef)
    or die "Cannot create proj";
defer { proj_destroy($pj); }

($easting, $northing) = ( 500_000, 6094_800 );
$a = proj_coord( $easting, $northing, 0, 'Inf' );
$b = proj_trans( $pj, PJ_FWD, $a );

printf "Target: easting %.2f, northing %.2f\n",
    $b->enu->e, $b->enu->n;

See also the example script eg/pj_obs_api_mini_demo.pl in this distribution.

DESCRIPTION

This module is a foreign function interface to the PROJ coordinate transformation library. Please see the PROJ library's C function reference for further documentation. You should be able to use those C functions as if they were Perl.

This module is very incomplete. Version 0.01 does only little more than what is necessary to support Geo::LibProj::cs2cs.

FUNCTIONS

Geo::LibProj::FFI currently offers the following functions.

Import all functions and constants by using the tag :all.

Threading contexts

  • proj_context_create

  • proj_context_destroy

  • proj_context_use_proj4_init_rules

Transformation setup

  • proj_create

  • proj_create_argv

  • proj_create_crs_to_crs

  • proj_create_crs_to_crs_from_pj

  • proj_normalize_for_visualization

  • proj_destroy

Coordinate transformation

  • proj_trans

Error reporting

  • proj_context_errno

  • proj_errno_string

  • proj_context_errno_string

Logging

  • proj_log_level

Info functions

  • proj_info

Various

  • proj_coord

Cleanup

  • proj_cleanup

DATA TYPES

The PROJ library uses numerous composite data types. When working with Geo::LibProj::FFI, members of C struct and union types may be accessed for reading by calling methods on these composites. For example, to output the X coordinate of a PJ_COORD value, you could simply do print $coord->xyz->x();. Please see the PROJ data type reference for further documentation.

As of version 0.02 of this module, the interface for modifying values of composite types from Perl is still evolving. Therefore, values of C struct and union types are best treated as immutable by Perl users. For the same reason, it is not recommended to try and create new values of such types using Perl constructors; instead, users should use PROJ functions to create such values wherever possible.

That said, it is already now fully possible to modify such values and to construct them using new(); it's just not yet recommended to do so. Consider this code example to create and modify a PJ_COORD value:

# discouraged:
# (not guaranteed to work in future versions)
$coord = Geo::LibProj::FFI::PJ_COORD->new({
    xy => { x => 12, y => 34 }
});
$coord->xyz->z( 100 );

# recommended:
$coord = proj_coord( 12, 34, 0, 0 );
$vector = $coord->v;
$vector->[2] = 100;
$coord = proj_coord( @$vector );

BUGS AND LIMITATIONS

PROJ makes heavy use of C union pass-by-value, which is unsupported by FFI::Platypus. In earlier versions of this module, the workaround for working with PJ_COORD values was quite slow. This performance issue has been addressed as of version 0.03.

Some implementation details of the glue this module provides may change in future, for example to better match the API or to increase performance. Should you decide to use this module in production, it would be wise to watch the GitHub project for changes, at least until the version has reached 1.00.

This module is designed to be used with PROJ version 8. PROJ versions as far back as 6.2.0 should work as well; please report any issues.

SEE ALSO

API LICENSE

The API this module gives access to is the proj.h API, which is available under the terms of the Expat MIT license.

Copyright (c) 2016, 2017, Thomas Knudsen / SDFE
Copyright (c) 2018, Even Rouault

The API designers didn't write this Perl module, and the module author didn't design the API.

AUTHOR

Arne Johannessen <ajnn@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2021 by Arne Johannessen.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)