pylon 5 Camera Software Suite for macOS for use with Basler 
Gigabit Ethernet(GigE) and Basler USB 3.0 Cameras (U3V)
================================================================


System Requirements
===================

GigE
----
A GigE network adapter that supports jumbo frames is recommended. Concerning 
performance and reliability we made best experiences with the on-board network 
adapter. Although the pylon software will work with any GigE network adapter, 
we recommend to use on-board adapters.

USB
---
For U3V devices a USB3-capable USB controller is necessary. For best 
performance and stability we highly recommend to use the on-board 
USB adapter.


Installation
=============

The installation of pylon for macOS is described in the INSTALL text document.


Performance Optimization
========================

To increase performance and to minimize CPU load when grabbing images, the 
following settings should be considered:

GigE Devices
------------
* Enable jumbo frames.
  Many GigE network adapters support so-called jumbo frames, i.e., network 
  packets larger than the usual 1500 bytes. To enable jumbo frames, the maximum 
  transfer unit (MTU) size of the PC's network adapter must be set to a high 
  value (see the description in the INSTALL document). We recommend using a 
  value of 8192.

* Increase the packet size.
  When jumbo frames are enabled, the camera's packet size must be increased to 
  benefit from the larger packets. The 'Optimizing Packet Size' section of the 
  INSTALL document describes how to set the packet size.

U3V Devices
-----------
* Increasing Packet Size
  For faster USB transfers you should increase the packet size. You can do this 
  by changing the "Stream Parameters" -> "Maximum Transfer Size" value from 
  inside the pylon Viewer or by setting the corresponding value via the API.


Documentation
=============

The pylon Camera Software Suite installation installs the pylon Programmer's Guide 
and API reference and the Basler Product Documentation in the Applications directory.
Both can be also accessed directly from pylon Viewer -> ?-menu. 


Sample Programs
===============

The installation disk image contains a set of sample programs. These sample 
programs are simple command line programs showing the basic pylon use cases. 
They are located in the "Samples/C++" folder. Each folder contains a top-level 
Apple Xcode project file that can be used to build the different sample programs.
You need to copy the Samples directory to a writable location, e.g. your home 
directory, before you can use it with Apple Xcode.


Camera Emulator
===============

In addition to camera transport layers like GigE Vision or USB3 Vision, pylon offers
a transport layer that can create simple camera emulation devices. This allows you to
develop applications without the need for a physical camera. It is also useful if you
want to develop a multi-camera application and don't have enough cameras at hand.
Besides emulating image acquisition and standard camera features, camera emulation
devices also offer features that a physical camera does not offer:
- You can display custom test images, e.g., to optimize your image processing algorithms.
- You can generate failed buffers, e.g., to test your exception handling routines.

The number of available emulator devices can be controlled by exporting the
PYLON_CAMEMU environment variable. For example,

   export PYLON_CAMEMU=2

will provide two emulator devices. These devices are accessible both by using
the pylon API and the pylon Viewer program.

When PYLON_CAMEMU is not set, no emulator devices are provided.
Note: A maximum of 256 emulator devices are supported.

For more information on the camera emulator refer to the Basler Product Documentation,
which is included in this package (press F1 in the pylon Viewer).


Troubleshooting
===============

In the event of running into any issues, generate a log file in the following way:
- Open the Terminal app (located in /Applications/Utilities).
- Run the pylon Viewer by executing the following command line in the Terminal app:

   /Library/Frameworks/pylon.framework/Versions/Current/Resources/Tools/pylon-start-with-
   logging.sh /Applications/pylon\ Viewer.app

Note: 
If you used a custom path during the pylon installation, "pylon-start-with-logging.sh" 
and "pylon Viewer.app" may be located in a different directory.

- Reproduce the issue, e.g., open a camera in the pylon Viewer, grab an image, close 
  the camera etc.
- Close the pylon Viewer. 
- A pylonLog.txt document including the logging information will open.
- Save the document and send it to Basler Support for further analysis.

 
Version Infos
=============

The pylon libraries have been built using the following tools.

macOS x86 64bit:
    These binaries are built with Apple LLVM version 9.0.0 (clang-900.0.37) 
    and Xcode 9.0 (9A235).