eye-ris v1.3 fixed point library reference eye-ris...

DECLARATION OF CONFORMITY

AS DEFINED BY THE COUNCIL DIRECTIVE 89/336/EEC

EMC (ELECTROMAGNETIC COMPABILITY) WE HEREWITH DECLARE THAT THIS PRODUCT

COMPLIES WITH THE FOLOWING PROVISIONS APPLYING TO IT. EN61000-6-2 EN61000-6-3

Sales Contacts

Europe/USA Rafael Romay Senior Business Development Director T. +34 954 081261

Japan/Asia Pacific IPN International Professional Networks Corporation Kanji Saruta CEO & President T.+81 (3) 521 23525

Israel/Middle East F.R.E.S.H Integrated Circuits Ltd. Fred Waldstein Managing Director T. +972 (9) 765 8805

Innovaciones Microelectrónicas S.L. · All Rights Reserved · www.anafocus.com

July 15, 2009

Eye-RIS v1.3 Fixed Point Library Reference

Eye-RIS v1.3 User’s Manual



Copyright, Trademarks and Patents

The software described in this document is furnished under license, and may be used or copied only in accordance with the terms of such license and with the inclusion of the copyright notice shown on this page. The software, this document, nor any copies thereof may be provided or otherwise made available to anyone other than the licensee. Title to and ownership of this software remains with Innovaciones Microelectrónicas S.L. or its licensor.

Innovaciones Microelectrónicas S.L. assumes no responsibility for the use or reliability of its software on equipment that is not supplied by Innovaciones Microelectrónicas S.L. Innovaciones Microelectrónicas S.L. makes no warranties, either express or implied, regarding the described software, its merchantability or its fitness for any particular purpose.

The information in this document is subject to change without notice and should not be construed as a commitment by Innovaciones Microelectrónicas S.L.. Innovaciones Microelectrónicas S.L. is not responsible for any errors that may be present in either this document or the associated software. This document may not be copied in whole or in part, nor transferred to any other media or language, without the written permission of Innovaciones Microelectrónicas S.L.

The hardware described in this document may be covered by one or more of the following European patents: 03769516.0 – 2203. Other European and foreign patents are pending.

The following are registered trademarks of Innovaciones Microelectrónicas:

- AnaFocus

- Eye-RIS

- AnaFocus’ Q-Eye

The following are trademarks of Innovaciones Microelectrónicas:

- The AnaFocus logo

- The Eye-RIS logo

Other product and company names mentioned herein are the trademarks, or registered trademarks, of their respective owners.



Precautions

Observe these precautions when installing the Eye-RIS™ v1.3 vision system to reduce the risk of injury or equipment damage:

Eye-RIS™ v1.3 vision systems are intended to be supplied by the provided Direct Plug-In Power Unit with a minimum output rated 5VDC, 500mA and marked Class 2, Limited Power Source (LPS). Any other voltage creates a risk of fire or shock and can damage the Eye-RIS™ components.

Do not install Eye-RIS™ v1.3 vision systems where they are directly exposed to environmental hazards such as excessive heat, dust, moisture, humidity, impact, vibration, corrosive substances, flammable substances, or static electricity.

To reduce the risk of damage or malfunction due to over-voltage, line noise, electrostatic discharge (ESD), power surges, or other irregularities in the power supply, route all cables and wires away from high-voltage power sources.

Do not open the Eye-RIS™ v1.3 vision system case. These devices do not contain user-serviceable parts.

Do not make electrical or mechanical modifications to the Eye-RIS™ v1.3 components. Unauthorized modifications may violate your warranty.

Do not use Eye-RIS™ v.13 in environments or applications where incorrect or missing output signal may cause human injury.

I/O ports must be handled with care. Short-circuits among I/O pins may damage the system.

Changes or modifications not expressly approved by the party responsible for regulatory compliance could void the user’s authority to operate the equipment.



Table of Contents

1. Introduction ............................................................................................................... 7

1.1. About this manual ................................................................................................................. 7

1.2. Assumptions.......................................................................................................................... 7

1.3. Naming and conventions ....................................................................................................... 7

2. The Fixed Point Library ............................................................................................... 8

2.1. Using fixed point data variables ............................................................................................ 9

2.1.1. Words of caution .......................................................................................................... 10

2.2. Naming schema .................................................................................................................. 10

3. Reference ................................................................................................................. 11

3.1. Conversion functions ........................................................................................................... 11

3.1.1. Float type values ........................................................................................................... 11

Fix_ftos .......................................................................................................................................... 11

Fix_ftoq .......................................................................................................................................... 11

Fix_ftok .......................................................................................................................................... 12

Fix_ftol ........................................................................................................................................... 12

Fix_stof .......................................................................................................................................... 13

Fix_qtod ......................................................................................................................................... 13

Fix_ktod ......................................................................................................................................... 14

Fix_ltod .......................................................................................................................................... 14

3.1.2. Integer type values ....................................................................................................... 14

Fix_itos .......................................................................................................................................... 15

Fix_itoq .......................................................................................................................................... 15

Fix_itok .......................................................................................................................................... 15

Fix_ftol ........................................................................................................................................... 16

Fix_stoi .......................................................................................................................................... 16

Fix_qtoi .......................................................................................................................................... 17

Fix_ktoi .......................................................................................................................................... 17

Fix_ltoi ........................................................................................................................................... 18



3.1.3. Fixed Point values ......................................................................................................... 18

Fix_stok .......................................................................................................................................... 18

Fix_ktos .......................................................................................................................................... 19

Fix_stol .......................................................................................................................................... 19

Fix_ltos .......................................................................................................................................... 19

Fix_ktol .......................................................................................................................................... 20

Fix_ltok .......................................................................................................................................... 20

3.2. Arithmetic operations.......................................................................................................... 21

3.2.1. Addition and subtraction .............................................................................................. 21

3.2.2. Multiplication ............................................................................................................... 21

Fix_smuls ....................................................................................................................................... 21

Fix_qmulq ...................................................................................................................................... 22

Fix_kmulk ....................................................................................................................................... 22

Fix_lmull ........................................................................................................................................ 23

3.2.3. Division ......................................................................................................................... 23

Fix_sdivs ........................................................................................................................................ 23

Fix_qdivq ....................................................................................................................................... 24

Fix_kdivk ........................................................................................................................................ 24

Fix_ldivl .......................................................................................................................................... 25

3.3. Square root ......................................................................................................................... 25

Fix_ksqrtk ...................................................................................................................................... 25

Fix_lsqrtl ........................................................................................................................................ 26

3.4. Trigonometric operations .................................................................................................... 26

3.4.1. Sine .............................................................................................................................. 26

Fix_ksink ........................................................................................................................................ 26

Fix_lsinl .......................................................................................................................................... 27

Fix_lsink ......................................................................................................................................... 27

3.4.2. Cosine ........................................................................................................................... 27

Fix_kcosk ....................................................................................................................................... 27

Fix_lcosl ......................................................................................................................................... 28

Fix_lcosk ........................................................................................................................................ 28

3.4.3. Tangent ........................................................................................................................ 29

Fix_ktank ....................................................................................................................................... 29

Fix_ltanl ......................................................................................................................................... 29

Fix_ltank ........................................................................................................................................ 30

3.4.4. Arc tangent ................................................................................................................... 30



Fix_katank ..................................................................................................................................... 30

Fix_latanl ....................................................................................................................................... 31

Fix_katan2k ................................................................................................................................... 31

Fix_latan2l ..................................................................................................................................... 32

3.5. Logarithmic operations ....................................................................................................... 32

Fix_klogk ........................................................................................................................................ 32

Fix_llogl ......................................................................................................................................... 33

Fix_klog10k .................................................................................................................................... 33

Fix_llog10l ..................................................................................................................................... 33



Eye-RIS Vision System v1.3 User’s Manual

7 of 34

1. Introduction

1.1. About this manual

This document is a full reference guide of the Fixed Point Library set of functions.

These functions are provided as part of the Eye-RIS v1.3 framework for the user of the system to be able to create applications and examples.

1.2. Assumptions

It is assumed that the reader has at least basic notions of C language.

1.3. Naming and conventions

Italics will be used for new terms when they are defined.

bold fonts is used for software environment options.

Courier New is used to show fragments of source code and names of instructions and functions.

“Code” label is used when referring to fragments of code.




8 of 34

2. The Fixed Point Library

In the Eye-RIS Vision System there is no hardware support for floating point due to the extra silicon area its implementation requires. Without this hardware support, all floating point operations must be emulated in software. However, this solution tends to be both memory and CPU-time consuming, limiting the rate at which algorithms can be executed.

By implementing algorithms using fixed point (integer) mathematics, a significant improvement in execution speed can be observed because of inherent integer math hardware support. The speed improvement does come at the cost of reduced range and accuracy of the algorithms variables.

There is actually not a standard library for that purpose. In embedded system development, practically everyone dealing with this matter ends up implementing their own set of fixed point functions.

The adopted Fixed Point Library for the Eye-RIS Vision System is that one developed by Maximilian Rosenblatt and Andreas Wolf for Atmel AVR processors and licensed under LGPL.

Fixed point math typically represents a number as a single data split between integer and fractional part. This fractal part may take up as many bits as different precision levels are required.

However, for simplicity’s sake, the library defines just four different types of fixed point data, with 8, 16, and 24 bits for the fractional part. These types are defined as follows:

typedef signed short fx8_8;

typedef signed long fx24_8;



Obviously, the more bits are used to represent the decimal part the less to represent the integer one. Therefore, a very precise decimal part forces inevitably a small range of integer values and vice versa. Some trade-off must then be carefully considered when choosing the best type for a given operation.




9 of 34

The dynamic range of fixed point values is much less than floating-point values with equivalent word sizes. Therefore, in order to avoid overflow or unreasonable quantization errors, fixed point values must be scaled. It’s vital to check the range of possible values in order to choose the type that fits best the application requirements.

Type Resolution1 Range

fx8_8 3.906 · 10¯³ -128 ≤ fx ≤ 127.996094

fx24_8 3.906 · 10¯³ -8388608 ≤ fx ≤ 8388607.996094

fx16_16 ~1.526 · 10¯⁵ -32768 ≤ fx ≤ 32767.999985

fx8_24 ~5.960 · 10¯⁸ -128 ≤ fx ≤ 127.999999

Table 1 – Range and resolution of fixed point data types

2.1. Using fixed point data variables

A fixed point variable is defined just as any other C variable:

fx8_8 fx;

Although defined as regular integer variables, fixed point data are supposed to contain fixed point values. These values can be obtained from a float value or from an integer literal using one of the conversion macros described in the following sections.

For example, the next sentences are valid instructions to assign a value to a fixed point variable:

fx = Fix_ftos(11.375);

fx = Fix_itos(3);

fx = 0x379a;

1 Fractional resolution is determined by the number of bits (QF):




10 of 34

Note that, as an integer variable, an integer value can be directly assigned to a fixed point variable. It’s only when some operation is performed on this data when it is actually interpreted as a fixed point number.

2.1.1. Words of caution

The library does not check fixed point arithmetic for overflows or underflows, so the programmer must take care to prevent for these conditions.

In addition, the programmer should be careful when converting to and from float values, as these operations use inevitably the float simulation library and tend to be slow. Their use then should be kept to a minimum.

2.2. Naming schema

The function naming schema uses s for fx8_8, q for fx24_8, k for fx16_16, and l for fxp8_24. Functions names are composed according this rule, with the

return type before the operation and the parameter type behind it. Thus, lmull would be a multiplication taking two fx8_24 and yielding a result of the same type.




11 of 34

3. Reference

This section describes each of the functions that make up the Fixed Point Library.

3.1. Conversion functions

The Fixed Point Library includes a series of functions to convert fixed point values from and to standard data types.

3.1.1. Float type values

Several macros to work with float values are provided by the library.

Fix_ftos

Syntax

#define Fix_ftos(f)

Description

Converts a float value to an fx8_8 value.

Parameters

f: a float value.

Returns

The converted fx8_8 value.

Fix_ftoq

Syntax




12 of 34

#define Fix_ftoq(f)

Description


Parameters

f: a float value.

Returns


Fix_ftok

Syntax

#define Fix_ftok(f)

Description


Parameters

f: a float value.

Returns


Fix_ftol

Syntax

#define Fix_ftol(f)

Description


Parameters




13 of 34

f: a float value.

Returns


Fix_stof

Syntax

#define Fix_stof(s)

Description

Converts an fx8_8 value to a float value.

Parameters

s: an fx8_8 value.

Returns

The converted float value.

Fix_qtod

Syntax

#define Fix_qtod(q)

Description

Converts an fx24_8 value to a double-precision value.

Parameters

q: an fx24_8 value.

Returns

The converted double-precision value.




14 of 34

Fix_ktod

Syntax

#define Fix_ktod(k)

Description


Parameters

k: an fx16_16 value.

Returns


Fix_ltod

Syntax

#define Fix_ltod(l)

Description


Parameters

l: an fx8_24 value.

Returns


3.1.2. Integer type values

Several macros to work with integer values are provided by the library.




15 of 34

Fix_itos

Syntax

#define Fix_itos(i)

Description

Converts an integer value to an fx8_8 value.

Parameters

i: integer value.

Returns


Fix_itoq

Syntax

#define Fix_itoq(i)

Description


Parameters

i: integer value.

Returns


Fix_itok

Syntax




16 of 34

#define Fix_itok(i)

Description


Parameters

i: integer value.

Returns


Fix_ftol

Syntax

#define Fix_itol(i)

Description


Parameters

i: integer value.

Returns


Fix_stoi

Syntax

#define Fix_stoi(s)

Description

Converts an fx8_8 value to an integer value.

Parameters




17 of 34

s: an fx8_8 value.

Returns

The converted integer value.

Fix_qtoi

Syntax

#define Fix_qtoi(q)

Description


Parameters

q: an fx24_8 value.

Returns


Fix_ktoi

Syntax

#define Fix_ktoi(k)

Description


Parameters


Returns





18 of 34

Fix_ltoi

Syntax

#define Fix_ltoi(l)

Description


Parameters

l: an fx8_24 value.

Returns


3.1.3. Fixed Point values

Several macros to work with fixed point values are provided by the library.

Fix_stok

Syntax

#define Fix_stok(s)

Description

Converts an fx8_8 value to an fx16_16 value.

Parameters

s: an fx8_8 value.

Returns





19 of 34

Fix_ktos

Syntax

#define Fix_ktos(k)

Description


Parameters


Returns


Fix_stol

Syntax

#define Fix_stol(s)

Description


Parameters

s: an fx8_8 value.

Returns


Fix_ltos

Syntax




20 of 34

#define Fix_ltos(l)

Description


Parameters

l: an fx8_24 value.

Returns


Fix_ktol

Syntax

#define Fix_ktol(k)

Description


Parameters


Returns


Fix_ltok

Syntax

#define Fix_ltok(l)

Description


Parameters




21 of 34

l: an fx8_24 value.

Returns


3.2. Arithmetic operations

This section covers all the functions used to perform arithmetic operations.

3.2.1. Addition and subtraction

Variables of the same fixed point data type can be added and subtracted using common operators, without the need of special functions.

3.2.2. Multiplication

Fix_smuls

Syntax

fx8_8 Fix_smuls(fx8_8 a, fx8_8 b)

Description

Multiplies two fx8_8 values.

Parameters

a: an fx8_8 value.

b: another fx8_8 value.

Returns

The product of a and b as an fx8_8 value.




22 of 34

Fix_qmulq

Syntax

fx24_8 Fix_qmulq(fx24_8 a, fx24_8 b)

Description


Parameters

a: an fx24_8 value.


Returns


Fix_kmulk

Syntax

fx16_16 Fix_kmulk(fx16_16 a, fx16_16 b)

Description


Parameters

a: an fx16_16 value.


Returns





23 of 34

Fix_lmull

Syntax

fx8_24 Fix_lmull(fx8_24 a, fx8_24 b)

Description


Parameters

a: an fx8_24 value.


Returns


3.2.3. Division

Warning!

If numerator and denominator are very different in their magnitudes either the integer part or the fractional one could not be big enough to hold the result, so the division might be somewhat inaccurate. Therefore, the programmer should check out the range of both operands.

Fix_sdivs

Syntax

fx8_8 Fix_sdivs(fx8_8 a, fx8_8 b)

Description

Divides two fx8_8 values.

Parameters

a: an fx8_8 numerator.




24 of 34

b: an fx8_8 denominator.

Returns

The division of a by b as an fx8_8 value.

Fix_qdivq

Syntax

fx24_8 Fix_qdivq(fx24_8 a, fx24_8 b)

Description


Parameters



Returns


Fix_kdivk

Syntax

fx16_16 Fix_kdivk(fx16_16 a, fx16_16 b)

Description


Parameters



Returns




25 of 34


Fix_ldivl

Syntax

fx8_24 Fix_ldivl(fx8_24 a, fx8_24 b)

Description


Parameters


b: another fx8_24 denominator.

Returns


3.3. Square root

Fix_ksqrtk

Syntax

#define Fix_ksqrtk(k)

Description

Computes the square root of an fx16_16 value.

Parameters


Returns

The square root of k as an fx16_16 value.




26 of 34

Fix_lsqrtl

Syntax

#define Fix_lsqrtl(l)

Description

Computes the square root of an fx8_24 value.

Parameters

l: an fx8_24 value.

Returns

The square root of l as an fx8_24 value.

3.4. Trigonometric operations

This section covers functions to perform trigonometric calculations.

3.4.1. Sine

Fix_ksink

Syntax

#define Fix_ksink(k)

Description

Computes the sine of an angle of k radians.

Parameters


Returns

The sine of k as an fx16_16 value.




27 of 34

Fix_lsinl

Syntax

#define Fix_lsinl(l)

Description

Computes the sine of an angle of l radians.

Parameters

l: an fx8_24 value.

Returns

The sine of l as an fx8_24 value.

Fix_lsink

Syntax

#define Fix_lsink(k)

Description

Computes the sine of an angle of k radians.

Parameters


Returns

The sine of k as an fx8_24 value.

3.4.2. Cosine

Fix_kcosk

Syntax




28 of 34

#define Fix_kcosk(k)

Description

Computes the cosine of an angle of k radians.

Parameters


Returns

The cosine of k as an fx16_16 value.

Fix_lcosl

Syntax

#define Fix_lcosl(l)

Description

Computes the cosine of an angle of l radians.

Parameters

l: an fx8_24 value.

Returns

The cosine of l as an fx8_24 value.

Fix_lcosk

Syntax

#define Fix_lcosk(k)

Description

Computes the cosine of an angle of k radians.

Parameters




29 of 34


Returns

The cosine of k as an fx8_24 value.

3.4.3. Tangent

Fix_ktank

Syntax

fx16_16 Fix_ktank(fx16_16 k)

Description

Computes the tangent of an angle of k radians.

Parameters


Returns

The tangent of k as an fx16_16 value.

Fix_ltanl

Syntax

fx8_24 Fix_ltanl(fx8_24 l)

Description

Computes the tangent of an angle of l radians.

Parameters

l: an fx8_24 value.

Returns




30 of 34

The tangent of l as an fx8_24 value.

Fix_ltank

Syntax

fx8_24 Fix_ltank(fx16_16 k)

Description

Computes the tangent of an angle of k radians.

Parameters


Returns

The tangent of k as an fx8_24 value.

3.4.4. Arc tangent

Fix_katank

Syntax

#define Fix_katank(k)

Description

Computes the arc tangent of k.

Parameters


Returns

The arc tangent of k as an fx16_16 value, expressed in radians and in the interval [-π/2, π/2].




31 of 34

Fix_latanl

Syntax

#define Fix_latanl(l)

Description

Computes the arc tangent of l.

Parameters

l: an fx8_24 value.

Returns

The arc tangent of l as an fx8_24 value, expressed in radians and in the interval [-π/2, π/2].

Fix_katan2k

Syntax

fx16_16 Fix_katan2k(fx16_16 x, fx16_16 y)

Description

Computes the arc tangent of y/x.

Parameters

x: an fx16_16 value representing an x coordinate.

y: an fx16_16 value representing an y coordinate.

Returns

The arc tangent of y/x as an fx16_16 value, expressed in radians and in the interval [-π, π].




32 of 34

Fix_latan2l

Syntax

fx8_24 Fix_latan2l(fx8_24 x, fx8_24 y)

Description

Computes the arc tangent of y/x.

Parameters

x: an fx8_24 value representing an x coordinate.

y: an fx8_24 value representing an y coordinate.

Returns

The arc tangent of y/x as an fx8_24 value, expressed in radians and in the interval [-π, π].

3.5. Logarithmic operations

This section covers functions to compute logarithmic calculations.

Fix_klogk

Syntax

fx16_16 Fix_klogk(fx16_16 k)

Description

Computes the natural logarithm of k.

Parameters


Returns

The natural logarithm of k as an fx16_16 value.




33 of 34

Fix_llogl

Syntax

fx8_24 Fix_llogl(fx8_24 l)

Description

Computes the natural logarithm of l.

Parameters

l: an fx8_24 value.

Returns

The natural logarithm of l as an fx8_24 value.

Fix_klog10k

Syntax

#define Fix_klog10k(k)

Description

Computes the common (base 10) logarithm of k.

Parameters


Returns

The common (base 10) logarithm of k as an fx16_16 value.

Fix_llog10l

Syntax




34 of 34

#define Fix_llog10l(l)

Description

Computes the common (base 10) logarithm of l.

Parameters

l: an fx8_24 value.

Returns

The common (base 10) logarithm of l as an fx8_24 value.

eye-ris v1.3 fixed point library reference eye-ris...

Documents